Tutorial

This tutorial will outline how to create a very simple notes app. The finished app is available on GitHub.

Setup

First the development environment needs to be set up. This can be done by either downloading the zip from the website or cloning it directly from GitHub:

  1. git clone git@github.com:nextcloud/server.git --branch $BRANCH
  2. cd server
  3. git submodule update --init

Note

$BRANCH is the desired Nextcloud branch (e.g. stable19 for Nextcloud 19, master for the upcoming release)

First you want to enable debug mode to get proper error messages. To do that set debug to true in the config/config.php file:

  1. <?php
  2. $CONFIG = array (
  3.     'debug' => true,
  4.     ... configuration goes here ...
  5. );

Note

PHP errors are logged to data/nextcloud.log

Now open another terminal window and start the development server:

  1. cd nextcloud
  2. php -S localhost:8080

Afterwards a skeleton app can be created in the app store.

Download the compressed file that contains the generated app and extract it into your apps/ directory. Afterwards the application can be enabled on the apps page.

The first basic app is now available at http://localhost:8080/index.php/apps/yourappid/

Routes & controllers

A typical web application consists of server side and client side code. The glue between those two parts are the URLs. In case of the notes app the following URLs will be used:

  • GET /: Returns the interface in HTML
  • GET /notes: Returns a list of all notes in JSON
  • GET /notes/1: Returns a note with the id 1 in JSON
  • DELETE /notes/1: Deletes a note with the id 1
  • POST /notes: Creates a new note by passing in JSON
  • PUT /notes/1: Updates a note with the id 1 by passing in JSON

On the client side we can call these URLs with the following jQuery code:

  1. // example for calling the PUT /notes/1 URL
  2. var baseUrl = OC.generateUrl('/apps/notestutorial');
  3. var note = {
  4.     title: 'New note',
  5.     content: 'This is the note text'
  6. };
  7. var id = 1;
  8. $.ajax({
  9.     url: baseUrl + '/notes/' + id,
  10.     type: 'PUT',
  11.     contentType: 'application/json',
  12.     data: JSON.stringify(note)
  13. }).done(function (response) {
  14.     // handle success
  15. }).fail(function (response, code) {
  16.     // handle failure
  17. });

On the server side we need to register a callback that is executed once the request comes in. The callback itself will be a method on a controller and the controller will be connected to the URL with a route. The controller and route for the page are already set up in notestutorial/appinfo/routes.php:

  1. <?php
  2. return ['routes' => [
  3.     ['name' => 'page#index', 'url' => '/', 'verb' => 'GET']
  4. ]];

This route calls the controller OCA\notestutorial\PageController->index() method which is defined in notestutorial/lib/Controller/PageController.php. The controller returns a template, in this case notestutorial/templates/main.php:

Note

@NoAdminRequired and @NoCSRFRequired in the comments above the method turn off security checks, see requests/controllers

  1. <?php
  2.  namespace OCA\NotesTutorial\Controller;
  4.  use OCP\IRequest;
  5.  use OCP\AppFramework\Http\TemplateResponse;
  6.  use OCP\AppFramework\Controller;
  8.  class PageController extends Controller {
  10.      public function __construct(string $AppName, IRequest $request){
  11.          parent::__construct($AppName, $request);
  12.      }
  14.      /**
  15.       * @NoAdminRequired
  16.       * @NoCSRFRequired
  17.       */
  18.      public function index() {
  19.          return new TemplateResponse('notestutorial', 'main');
  20.      }
  22.  }

Since the route which returns the initial HTML has been taken care of, the controller which handles the AJAX requests for the notes needs to be set up. Create the following file: notestutorial/lib/Controller/NoteController.php with the following content:

  1. <?php
  2.  namespace OCA\NotesTutorial\Controller;
  4.  use OCP\IRequest;
  5.  use OCP\AppFramework\Controller;
  7.  class NoteController extends Controller {
  9.      public function __construct(string $AppName, IRequest $request){
  10.          parent::__construct($AppName, $request);
  11.      }
  13.      /**
  14.       * @NoAdminRequired
  15.       */
  16.      public function index() {
  17.          // empty for now
  18.      }
  20.      /**
  21.       * @NoAdminRequired
  22.       *
  23.       * @param int $id
  24.       */
  25.      public function show(int $id) {
  26.          // empty for now
  27.      }
  29.      /**
  30.       * @NoAdminRequired
  31.       *
  32.       * @param string $title
  33.       * @param string $content
  34.       */
  35.      public function create(string $title, string $content) {
  36.          // empty for now
  37.      }
  39.      /**
  40.       * @NoAdminRequired
  41.       *
  42.       * @param int $id
  43.       * @param string $title
  44.       * @param string $content
  45.       */
  46.      public function update(int $id, string $title, string $content) {
  47.          // empty for now
  48.      }
  50.      /**
  51.       * @NoAdminRequired
  52.       *
  53.       * @param int $id
  54.       */
  55.      public function destroy(int $id) {
  56.          // empty for now
  57.      }
  59.  }

Note

The parameters are extracted from the request body and the URL using the controller method’s variable names. Since PHP does not support type hints for primitive types such as ints and booleans, we need to add them as annotations in the comments. In order to type cast a parameter to an int, add @param int $parameterName

Now the controller methods need to be connected to the corresponding URLs in the notestutorial/appinfo/routes.php file:

  1. <?php
  2. return [
  3.     'routes' => [
  4.         ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
  5.         ['name' => 'note#index', 'url' => '/notes', 'verb' => 'GET'],
  6.         ['name' => 'note#show', 'url' => '/notes/{id}', 'verb' => 'GET'],
  7.         ['name' => 'note#create', 'url' => '/notes', 'verb' => 'POST'],
  8.         ['name' => 'note#update', 'url' => '/notes/{id}', 'verb' => 'PUT'],
  9.         ['name' => 'note#destroy', 'url' => '/notes/{id}', 'verb' => 'DELETE']
  10.     ]
  11. ];

Since those 5 routes are so common, they can be abbreviated by adding a resource instead:

  1. <?php
  2. return [
  3.     'resources' => [
  4.         'note' => ['url' => '/notes']
  5.     ],
  6.     'routes' => [
  7.         ['name' => 'page#index', 'url' => '/', 'verb' => 'GET']
  8.     ]
  9. ];

Database

Now that the routes are set up and connected the notes should be saved in the database. To do that first create a database migration by creating a file notestutorial/lib/Migration/VersionXXYYZZDateYYYYMMDDHHSSAA.php, so for example notestutorial/lib/Migration/Version000000Date20181013124731.php“”

  1. <?php
  3.   namespace OCA\NotesTutorial\Migration;
  5.   use Closure;
  6.   use OCP\DB\ISchemaWrapper;
  7.   use OCP\Migration\SimpleMigrationStep;
  8.   use OCP\Migration\IOutput;
  10.   class Version1400Date20181013124731 extends SimpleMigrationStep {
  12.     /**
  13.     * @param IOutput $output
  14.     * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
  15.     * @param array $options
  16.     * @return null|ISchemaWrapper
  17.     */
  18.     public function changeSchema(IOutput $output, Closure $schemaClosure, array $options) {
  19.         /** @var ISchemaWrapper $schema */
  20.         $schema = $schemaClosure();
  22.         if (!$schema->hasTable('notestutorial')) {
  23.             $table = $schema->createTable('notestutorial');
  24.             $table->addColumn('id', 'integer', [
  25.                 'autoincrement' => true,
  26.                 'notnull' => true,
  27.             ]);
  28.             $table->addColumn('title', 'string', [
  29.                 'notnull' => true,
  30.                 'length' => 200
  31.             ]);
  32.             $table->addColumn('user_id', 'string', [
  33.                 'notnull' => true,
  34.                 'length' => 200,
  35.             ]);
  36.             $table->addColumn('content', 'text', [
  37.                 'notnull' => true,
  38.                 'default' => ''
  39.             ]);
  41.             $table->setPrimaryKey(['id']);
  42.             $table->addIndex(['user_id'], 'notestutorial_user_id_index');
  43.         }
  44.         return $schema;
  45.     }
  46. }

To create the tables in the database, run the migration command:

  1. php ./occ migrations:execute <appId> <versionNumber>
  3. Example: sudo -u www-data php ./occ migrations:execute photos 000000Date20201002183800

Note

to trigger the table creation/alteration when user updating the app, update the version tag in notestutorial/appinfo/info.xml . migration will be executed when user reload page after app upgrade

  1. <?xml version="1.0"?>
  2.   <info>
  3.       <id>notestutorial</id>
  4.       <name>Notes Tutorial</name>
  5.       <description>My first Nextcloud app</description>
  6.       <licence>AGPL</licence>
  7.       <author>Your Name</author>
  8.       <version>0.0.2</version>
  9.       <namespace>notestutorial</namespace>
  10.       <category>tool</category>
  11.       <dependencies>
  12.           <owncloud min-version="8" />
  13.       </dependencies>
  14.   </info>

Now that the tables are created we want to map the database result to a PHP object to be able to control data. First create an entity in notestutorial/lib/Db/Note.php:

  1. <?php
  2. namespace OCA\NotesTutorial\Db;
  4. use JsonSerializable;
  6. use OCP\AppFramework\Db\Entity;
  8. class Note extends Entity implements JsonSerializable {
  10.     protected $title;
  11.     protected $content;
  12.     protected $userId;
  14.     public function __construct() {
  15.         $this->addType('id','integer');
  16.     }
  18.     public function jsonSerialize() {
  19.         return [
  20.             'id' => $this->id,
  21.             'title' => $this->title,
  22.             'content' => $this->content
  23.         ];
  24.     }
  25. }

Note

A field id is automatically set in the Entity base class

We also define a jsonSerializable method and implement the interface to be able to transform the entity to JSON easily.

Entities are returned from so-called Mappers. Let’s create one in notestutorial/lib/Db/NoteMapper.php and add a find and findAll method:

  1. <?php
  2. namespace OCA\NotesTutorial\Db;
  4. use OCP\IDBConnection;
  5. use OCP\AppFramework\Db\QBMapper;
  7. class NoteMapper extends QBMapper {
  9.     public function __construct(IDBConnection $db) {
  10.         parent::__construct($db, 'notestutorial_notes', Note::class);
  11.     }
  13.     public function find(int $id, string $userId) {
  14.         $qb = $this->db->getQueryBuilder();
  16.                     $qb->select('*')
  17.                              ->from($this->getTableName())
  18.                              ->where(
  19.                                      $qb->expr()->eq('id', $qb->createNamedParameter($id))
  20.                              )->andWhere(
  21.              $qb->expr()->eq('user_id', $qb->createNamedParameter($userId))
  22.            );
  24.         return $this->findEntity($qb);
  25.     }
  27.     public function findAll(string $userId) {
  28.         $qb = $this->db->getQueryBuilder();
  30.         $qb->select('*')
  31.            ->from($this->getTableName())
  32.            ->where(
  33.             $qb->expr()->eq('user_id', $qb->createNamedParameter($userId))
  34.            );
  36.         return $this->findEntities($qb);
  37.     }
  39. }

Note

The first parent constructor parameter is the database layer, the second one is the database table and the third is the entity on which the result should be mapped onto. Insert, delete and update methods are already implemented.

Connect database & controllers

The mapper which provides the database access is finished and can be passed into the controller.

You can pass in the mapper by adding it as a type hinted parameter. Nextcloud will figure out how to assemble them by itself. Additionally we want to know the userId of the currently logged in user. Simply add a $UserId parameter to the constructor (case sensitive!). To do that open notestutorial/lib/Controller/NoteController.php and change it to the following:

  1. <?php
  2.  namespace OCA\NotesTutorial\Controller;
  4.  use Exception;
  6.  use OCP\IRequest;
  7.  use OCP\AppFramework\Http;
  8.  use OCP\AppFramework\Http\DataResponse;
  9.  use OCP\AppFramework\Controller;
  11.  use OCA\NotesTutorial\Db\Note;
  12.  use OCA\NotesTutorial\Db\NoteMapper;
  14.  class NoteController extends Controller {
  16.      private $mapper;
  17.      private $userId;
  19.      public function __construct(string $AppName, IRequest $request, NoteMapper $mapper, $UserId){
  20.          parent::__construct($AppName, $request);
  21.          $this->mapper = $mapper;
  22.          $this->userId = $UserId;
  23.      }
  25.      /**
  26.       * @NoAdminRequired
  27.       */
  28.      public function index() {
  29.          return new DataResponse($this->mapper->findAll($this->userId));
  30.      }
  32.      /**
  33.       * @NoAdminRequired
  34.       *
  35.       * @param int $id
  36.       */
  37.      public function show(int $id) {
  38.          try {
  39.              return new DataResponse($this->mapper->find($id, $this->userId));
  40.          } catch(Exception $e) {
  41.              return new DataResponse([], Http::STATUS_NOT_FOUND);
  42.          }
  43.      }
  45.      /**
  46.       * @NoAdminRequired
  47.       *
  48.       * @param string $title
  49.       * @param string $content
  50.       */
  51.      public function create(string $title, string $content) {
  52.          $note = new Note();
  53.          $note->setTitle($title);
  54.          $note->setContent($content);
  55.          $note->setUserId($this->userId);
  56.          return new DataResponse($this->mapper->insert($note));
  57.      }
  59.      /**
  60.       * @NoAdminRequired
  61.       *
  62.       * @param int $id
  63.       * @param string $title
  64.       * @param string $content
  65.       */
  66.      public function update(int $id, string $title, string $content) {
  67.          try {
  68.              $note = $this->mapper->find($id, $this->userId);
  69.          } catch(Exception $e) {
  70.              return new DataResponse([], Http::STATUS_NOT_FOUND);
  71.          }
  72.          $note->setTitle($title);
  73.          $note->setContent($content);
  74.          return new DataResponse($this->mapper->update($note));
  75.      }
  77.      /**
  78.       * @NoAdminRequired
  79.       *
  80.       * @param int $id
  81.       */
  82.      public function destroy(int $id) {
  83.          try {
  84.              $note = $this->mapper->find($id, $this->userId);
  85.          } catch(Exception $e) {
  86.              return new DataResponse([], Http::STATUS_NOT_FOUND);
  87.          }
  88.          $this->mapper->delete($note);
  89.          return new DataResponse($note);
  90.      }
  92.  }

Note

The actual exceptions are OCP\AppFramework\Db\DoesNotExistException and OCP\AppFramework\Db\MultipleObjectsReturnedException but in this example we will treat them as the same. DataResponse is a more generic response than JSONResponse and also works with JSON.

This is all that is needed on the server side. Now let’s progress to the client side.

Making things reusable and decoupling controllers from the database

Let’s say our app is now on the app store and we get a request that we should save the files in the filesystem which requires access to the filesystem.

The filesystem API is quite different from the database API and throws different exceptions, which means we need to rewrite everything in the NoteController class to use it. This is bad because a controller’s only responsibility should be to deal with incoming Http requests and return Http responses. If we need to change the controller because the data storage was changed the code is probably too tightly coupled and we need to add another layer in between. This layer is called Service.

Let’s take the logic that was inside the controller and put it into a separate class inside notestutorial/lib/Service/NoteService.php:

  1. <?php
  2. namespace OCA\NotesTutorial\Service;
  4. use Exception;
  6. use OCP\AppFramework\Db\DoesNotExistException;
  7. use OCP\AppFramework\Db\MultipleObjectsReturnedException;
  9. use OCA\NotesTutorial\Db\Note;
  10. use OCA\NotesTutorial\Db\NoteMapper;
  13. class NoteService {
  15.     private $mapper;
  17.     public function __construct(NoteMapper $mapper){
  18.         $this->mapper = $mapper;
  19.     }
  21.     public function findAll(string $userId) {
  22.         return $this->mapper->findAll($userId);
  23.     }
  25.     private function handleException ($e) {
  26.         if ($e instanceof DoesNotExistException ||
  27.             $e instanceof MultipleObjectsReturnedException) {
  28.             throw new NotFoundException($e->getMessage());
  29.         } else {
  30.             throw $e;
  31.         }
  32.     }
  34.     public function find(int $id, string $userId) {
  35.         try {
  36.             return $this->mapper->find($id, $userId);
  38.         // in order to be able to plug in different storage backends like files
  39.         // for instance it is a good idea to turn storage related exceptions
  40.         // into service related exceptions so controllers and service users
  41.         // have to deal with only one type of exception
  42.         } catch(Exception $e) {
  43.             $this->handleException($e);
  44.         }
  45.     }
  47.     public function create(string $title, string $content, string $userId) {
  48.         $note = new Note();
  49.         $note->setTitle($title);
  50.         $note->setContent($content);
  51.         $note->setUserId($userId);
  52.         return $this->mapper->insert($note);
  53.     }
  55.     public function update(int $id, string $title, string $content, string $userId) {
  56.         try {
  57.             $note = $this->mapper->find($id, $userId);
  58.             $note->setTitle($title);
  59.             $note->setContent($content);
  60.             return $this->mapper->update($note);
  61.         } catch(Exception $e) {
  62.             $this->handleException($e);
  63.         }
  64.     }
  66.     public function delete(int $id, string $userId) {
  67.         try {
  68.             $note = $this->mapper->find($id, $userId);
  69.             $this->mapper->delete($note);
  70.             return $note;
  71.         } catch(Exception $e) {
  72.             $this->handleException($e);
  73.         }
  74.     }
  76. }

Following up create the exceptions in notestutorial/lib/Service/ServiceException.php:

  1. <?php
  2. namespace OCA\NotesTutorial\Service;
  4. use Exception;
  6. class ServiceException extends Exception {}

and notestutorial/lib/Service/NotFoundException.php:

  1. <?php
  2. namespace OCA\NotesTutorial\Service;
  4. class NotFoundException extends ServiceException {}

Remember how we had all those ugly try catches that where checking for DoesNotExistException and simply returned a 404 response? Let’s also put this into a reusable class. In our case we chose a trait so we can inherit methods without having to add it to our inheritance hierarchy. This will be important later on when you’ve got controllers that inherit from the ApiController class instead.

The trait is created in notestutorial/lib/Controller/Errors.php:

  1. <?php
  3. namespace OCA\NotesTutorial\Controller;
  5. use Closure;
  7. use OCP\AppFramework\Http;
  8. use OCP\AppFramework\Http\DataResponse;
  10. use OCA\NotesTutorial\Service\NotFoundException;
  13. trait Errors {
  15.     protected function handleNotFound (Closure $callback) {
  16.         try {
  17.             return new DataResponse($callback());
  18.         } catch(NotFoundException $e) {
  19.             $message = ['message' => $e->getMessage()];
  20.             return new DataResponse($message, Http::STATUS_NOT_FOUND);
  21.         }
  22.     }
  24. }

Now we can wire up the trait and the service inside the NoteController:

  1. <?php
  2. namespace OCA\NotesTutorial\Controller;
  4. use OCP\IRequest;
  5. use OCP\AppFramework\Http\DataResponse;
  6. use OCP\AppFramework\Controller;
  8. use OCA\NotesTutorial\Service\NoteService;
  10. class NoteController extends Controller {
  12.     private $service;
  13.     private $userId;
  15.     use Errors;
  17.     public function __construct(string $AppName, IRequest $request,
  18.                                 NoteService $service, $UserId){
  19.         parent::__construct($AppName, $request);
  20.         $this->service = $service;
  21.         $this->userId = $UserId;
  22.     }
  24.     /**
  25.      * @NoAdminRequired
  26.      */
  27.     public function index() {
  28.         return new DataResponse($this->service->findAll($this->userId));
  29.     }
  31.     /**
  32.      * @NoAdminRequired
  33.      *
  34.      * @param int $id
  35.      */
  36.     public function show(int $id) {
  37.         return $this->handleNotFound(function () use ($id) {
  38.             return $this->service->find($id, $this->userId);
  39.         });
  40.     }
  42.     /**
  43.      * @NoAdminRequired
  44.      *
  45.      * @param string $title
  46.      * @param string $content
  47.      */
  48.     public function create(string $title, string $content) {
  49.         return $this->service->create($title, $content, $this->userId);
  50.     }
  52.     /**
  53.      * @NoAdminRequired
  54.      *
  55.      * @param int $id
  56.      * @param string $title
  57.      * @param string $content
  58.      */
  59.     public function update(int $id, string $title, string $content) {
  60.         return $this->handleNotFound(function () use ($id, $title, $content) {
  61.             return $this->service->update($id, $title, $content, $this->userId);
  62.         });
  63.     }
  65.     /**
  66.      * @NoAdminRequired
  67.      *
  68.      * @param int $id
  69.      */
  70.     public function destroy(int $id) {
  71.         return $this->handleNotFound(function () use ($id) {
  72.             return $this->service->delete($id, $this->userId);
  73.         });
  74.     }
  76. }

Great! Now the only reason that the controller needs to be changed is when request/response related things change.

Writing a test for the controller (recommended)

Tests are essential for having happy users and a carefree life. No one wants their users to rant about your app breaking their Nextcloud or being buggy. To do that you need to test your app. Since this amounts to a ton of repetitive tasks, we need to automate the tests.

Unit tests

A unit test is a test that tests a class in isolation. It is very fast and catches most of the bugs, so we want many unit tests.

Because Nextcloud uses Dependency Injection to assemble your app, it is very easy to write unit tests by passing mocks into the constructor. A simple test for the update method can be added by adding this to notestutorial/tests/Unit/Controller/NoteControllerTest.php:

  1. <?php
  2. namespace OCA\NotesTutorial\Tests\Unit\Controller;
  4. use PHPUnit_Framework_TestCase;
  6. use OCP\AppFramework\Http;
  7. use OCP\AppFramework\Http\DataResponse;
  9. use OCA\NotesTutorial\Service\NotFoundException;
  12. class NoteControllerTest extends PHPUnit_Framework_TestCase {
  14.     protected $controller;
  15.     protected $service;
  16.     protected $userId = 'john';
  17.     protected $request;
  19.     public function setUp() {
  20.         $this->request = $this->getMockBuilder('OCP\IRequest')->getMock();
  21.         $this->service = $this->getMockBuilder('OCA\NotesTutorial\Service\NoteService')
  22.             ->disableOriginalConstructor()
  23.             ->getMock();
  24.         $this->controller = new NoteController(
  25.             'notestutorial', $this->request, $this->service, $this->userId
  26.         );
  27.     }
  29.     public function testUpdate() {
  30.         $note = 'just check if this value is returned correctly';
  31.         $this->service->expects($this->once())
  32.             ->method('update')
  33.             ->with($this->equalTo(3),
  34.                     $this->equalTo('title'),
  35.                     $this->equalTo('content'),
  36.                    $this->equalTo($this->userId))
  37.             ->will($this->returnValue($note));
  39.         $result = $this->controller->update(3, 'title', 'content');
  41.         $this->assertEquals($note, $result->getData());
  42.     }
  45.     public function testUpdateNotFound() {
  46.         // test the correct status code if no note is found
  47.         $this->service->expects($this->once())
  48.             ->method('update')
  49.             ->will($this->throwException(new NotFoundException()));
  51.         $result = $this->controller->update(3, 'title', 'content');
  53.         $this->assertEquals(Http::STATUS_NOT_FOUND, $result->getStatus());
  54.     }
  56. }

We can and should also create a test for the NoteService class:

  1. <?php
  2. namespace OCA\NotesTutorial\Tests\Unit\Service;
  4. use PHPUnit_Framework_TestCase;
  6. use OCP\AppFramework\Db\DoesNotExistException;
  8. use OCA\NotesTutorial\Db\Note;
  10. class NoteServiceTest extends PHPUnit_Framework_TestCase {
  12.     private $service;
  13.     private $mapper;
  14.     private $userId = 'john';
  16.     public function setUp() {
  17.         $this->mapper = $this->getMockBuilder('OCA\NotesTutorial\Db\NoteMapper')
  18.             ->disableOriginalConstructor()
  19.             ->getMock();
  20.         $this->service = new NoteService($this->mapper);
  21.     }
  23.     public function testUpdate() {
  24.         // the existing note
  25.         $note = Note::fromRow([
  26.             'id' => 3,
  27.             'title' => 'yo',
  28.             'content' => 'nope'
  29.         ]);
  30.         $this->mapper->expects($this->once())
  31.             ->method('find')
  32.             ->with($this->equalTo(3))
  33.             ->will($this->returnValue($note));
  35.         // the note when updated
  36.         $updatedNote = Note::fromRow(['id' => 3]);
  37.         $updatedNote->setTitle('title');
  38.         $updatedNote->setContent('content');
  39.         $this->mapper->expects($this->once())
  40.             ->method('update')
  41.             ->with($this->equalTo($updatedNote))
  42.             ->will($this->returnValue($updatedNote));
  44.         $result = $this->service->update(3, 'title', 'content', $this->userId);
  46.         $this->assertEquals($updatedNote, $result);
  47.     }
  50.     /**
  51.      * @expectedException OCA\NotesTutorial\Service\NotFoundException
  52.      */
  53.     public function testUpdateNotFound() {
  54.         // test the correct status code if no note is found
  55.         $this->mapper->expects($this->once())
  56.             ->method('find')
  57.             ->with($this->equalTo(3))
  58.             ->will($this->throwException(new DoesNotExistException('')));
  60.         $this->service->update(3, 'title', 'content', $this->userId);
  61.     }
  63. }

If PHPUnit in version 8 is installed we can run the tests inside notestutorial/ with the following command:

  1. phpunit

Note

You need to adjust the notestutorial/tests/Unit/Controller/PageControllerTest file to get the tests passing: remove the testEcho method since that method is no longer present in your PageController and do not test the user id parameters since they are not passed anymore

Integration tests

Integration tests are slow and need a fully working instance but make sure that our classes work well together. Instead of mocking out all classes and parameters we can decide whether to use full instances or replace certain classes. Because they are slow we don’t want as many integration tests as unit tests.

In our case we want to create an integration test for the update method without mocking out the NoteMapper class so we actually write to the existing database.

To do that create a new file called notestutorial/tests/Integration/NoteIntegrationTest.php with the following content:

  1. <?php
  2. namespace OCA\NotesTutorial\Tests\Integration\Controller;
  4. use OCP\AppFramework\Http\DataResponse;
  5. use OCP\AppFramework\App;
  6. use Test\TestCase;
  8. use OCA\NotesTutorial\Db\Note;
  10. /**
  11.  * @group DB
  12.  */
  13. class NoteIntegrationTest extends TestCase {
  15.     private $controller;
  16.     private $mapper;
  17.     private $userId = 'john';
  19.     public function setUp() {
  20.         parent::setUp();
  21.         $app = new App('notestutorial');
  22.         $container = $app->getContainer();
  24.         // only replace the user id
  25.         $container->registerService('UserId', function($c) {
  26.             return $this->userId;
  27.         });
  29.         $this->controller = $container->query(
  30.             'OCA\NotesTutorial\Controller\NoteController'
  31.         );
  33.         $this->mapper = $container->query(
  34.             'OCA\NotesTutorial\Db\NoteMapper'
  35.         );
  36.     }
  38.     public function testUpdate() {
  39.         // create a new note that should be updated
  40.         $note = new Note();
  41.         $note->setTitle('old_title');
  42.         $note->setContent('old_content');
  43.         $note->setUserId($this->userId);
  45.         $id = $this->mapper->insert($note)->getId();
  47.         // fromRow does not set the fields as updated
  48.         $updatedNote = Note::fromRow([
  49.             'id' => $id,
  50.             'user_id' => $this->userId
  51.         ]);
  52.         $updatedNote->setContent('content');
  53.         $updatedNote->setTitle('title');
  55.         $result = $this->controller->update($id, 'title', 'content');
  57.         $this->assertEquals($updatedNote, $result->getData());
  59.         // clean up
  60.         $this->mapper->delete($result->getData());
  61.     }
  63. }

To run the integration tests change into the notestutorial directory and run:

  1. phpunit -c phpunit.integration.xml

Adding a RESTful API (optional)

A RESTful API allows other apps such as Android or iPhone apps to access and change your notes. Since syncing is a big core component of Nextcloud it is a good idea to add (and document!) your own RESTful API.

Because we put our logic into the NoteService class it is very easy to reuse it. The only pieces that need to be changed are the annotations which disable the CSRF check (not needed for a REST call usually) and add support for CORS so your API can be accessed from other webapps.

With that in mind create a new controller in notestutorial/lib/Controller/NoteApiController.php:

  1. <?php
  2. namespace OCA\NotesTutorial\Controller;
  4. use OCP\IRequest;
  5. use OCP\AppFramework\Http\DataResponse;
  6. use OCP\AppFramework\ApiController;
  8. use OCA\NotesTutorial\Service\NoteService;
  10. class NoteApiController extends ApiController {
  12.     private $service;
  13.     private $userId;
  15.     use Errors;
  17.     public function __construct($AppName, IRequest $request,
  18.                                 NoteService $service, $UserId){
  19.         parent::__construct($AppName, $request);
  20.         $this->service = $service;
  21.         $this->userId = $UserId;
  22.     }
  24.     /**
  25.      * @CORS
  26.      * @NoCSRFRequired
  27.      * @NoAdminRequired
  28.      */
  29.     public function index() {
  30.         return new DataResponse($this->service->findAll($this->userId));
  31.     }
  33.     /**
  34.      * @CORS
  35.      * @NoCSRFRequired
  36.      * @NoAdminRequired
  37.      *
  38.      * @param int $id
  39.      */
  40.     public function show($id) {
  41.         return $this->handleNotFound(function () use ($id) {
  42.             return $this->service->find($id, $this->userId);
  43.         });
  44.     }
  46.     /**
  47.      * @CORS
  48.      * @NoCSRFRequired
  49.      * @NoAdminRequired
  50.      *
  51.      * @param string $title
  52.      * @param string $content
  53.      */
  54.     public function create($title, $content) {
  55.         return $this->service->create($title, $content, $this->userId);
  56.     }
  58.     /**
  59.      * @CORS
  60.      * @NoCSRFRequired
  61.      * @NoAdminRequired
  62.      *
  63.      * @param int $id
  64.      * @param string $title
  65.      * @param string $content
  66.      */
  67.     public function update($id, $title, $content) {
  68.         return $this->handleNotFound(function () use ($id, $title, $content) {
  69.             return $this->service->update($id, $title, $content, $this->userId);
  70.         });
  71.     }
  73.     /**
  74.      * @CORS
  75.      * @NoCSRFRequired
  76.      * @NoAdminRequired
  77.      *
  78.      * @param int $id
  79.      */
  80.     public function destroy($id) {
  81.         return $this->handleNotFound(function () use ($id) {
  82.             return $this->service->delete($id, $this->userId);
  83.         });
  84.     }
  86. }

All that is left is to connect the controller to a route and enable the built in preflighted CORS method which is defined in the ApiController base class:

  1. <?php
  2. return [
  3.     'resources' => [
  4.         'note' => ['url' => '/notes'],
  5.         'note_api' => ['url' => '/api/0.1/notes']
  6.     ],
  7.     'routes' => [
  8.         ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
  9.         ['name' => 'note_api#preflighted_cors', 'url' => '/api/0.1/{path}',
  10.          'verb' => 'OPTIONS', 'requirements' => ['path' => '.+']]
  11.     ]
  12. ];

Note

It is a good idea to version your API in your URL

You can test the API by running a GET request with curl:

  1. curl -u user:password http://localhost:8080/index.php/apps/notestutorial/api/0.1/notes

Since the NoteApiController is basically identical to the NoteController, the unit test for it simply inherits its tests from the NoteControllerTest. Create the file notestutorial/tests/Unit/Controller/NoteApiControllerTest.php:

  1. <?php
  2. namespace OCA\NotesTutorial\Tests\Unit\Controller;
  4. require_once __DIR__ . '/NoteControllerTest.php';
  6. class NoteApiControllerTest extends NoteControllerTest {
  8.     public function setUp() {
  9.         parent::setUp();
  10.         $this->controller = new NoteApiController(
  11.             'notestutorial', $this->request, $this->service, $this->userId
  12.         );
  13.     }
  15. }

Building the frontend

To create a modern webapp you need to write JavaScript. You can use any JavaScript framework, but this tutorial focusses on a simple frontend using Vue.js. For a more detailed introduction to Vue.js please head over to the official documentation.

The source files of our frontend will be stored in the src/ directory. We use webpack for bundling the files and output of that will be stored in js/notestutorial.js.

The template of our view will be very simple due to the fact that Vue.js is taking care of all frontend rendering. We only need to load the main script bundle and add a div that will be replaced by our Vue app at runtime:

  1. <?php
  2. script('notestutorial', 'notestutorial');
  4. <div id="content"></div>

The frontend source code will consist of two files:

  • main.js which is the main entry point of our javascript code that gets loaded when the page is opened
  • App.vue which is our one single file component that takes care of all logic inside of the Vue app. Our example app contains some additional comments to explain how the frontend is built.

Congratulations! You’ve written your first Nextcloud app. You can now either try to further improve the tutorial notes app or start writing your own app.