Add more documentation to help beginners

src/Command/TestCommand.php

@@ -9,6 +9,11 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
+/**
+ * This is an example command.
+ * You can execute it with "php bin/console dbp:my-custom-command my-argument".
+ * Change "my-custom-command" to a more meaningful name in $defaultName.
+ */
 class TestCommand extends Command
 {
     protected static $defaultName = 'dbp:my-custom-command';

src/Controller/LoggedInOnly.php

@@ -8,6 +8,9 @@ use Dbp\Relay\ExampleBundle\Entity\Place;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * This is an example controller that only allows logged-in users to access it.
+ */
 class LoggedInOnly extends AbstractController
 {
     public function __invoke(Place $data, Request $request): Place

src/DataPersister/PlaceDataPersister.php

@@ -9,6 +9,9 @@ use Dbp\Relay\ExampleBundle\Entity\Place;
 use Dbp\Relay\ExampleBundle\Service\PlaceProviderInterface;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
+/**
+ * This is an example of a data persister where you can persist data for example with the help of a service that implements the PlaceProviderInterface.
+ */
 class PlaceDataPersister extends AbstractController implements DataPersisterInterface
 {
     private $api;
@@ -25,7 +28,13 @@ class PlaceDataPersister extends AbstractController implements DataPersisterInte
 
     public function persist($data): void
     {
-        // TODO
+        // TODO: Enable this if a user needs to be authenticated to persist data
+//        $this->denyAccessUnlessGranted('IS_AUTHENTICATED_FULLY');
+
+        // TODO: Enable this if a user needs to have a specific role to persist data
+//        $this->denyAccessUnlessGranted('ROLE_SCOPE_EXAMPLE');
+
+        $this->api->storePlace($data);
     }
 
     public function remove($data)

src/DataProvider/PlaceCollectionDataProvider.php

@@ -11,6 +11,9 @@ use Dbp\Relay\ExampleBundle\Entity\Place;
 use Dbp\Relay\ExampleBundle\Service\PlaceProviderInterface;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
+/**
+ * This is an example of a collection data provider that uses the PlaceProviderInterface to get the data for a collection of items.
+ */
 final class PlaceCollectionDataProvider extends AbstractController implements CollectionDataProviderInterface, RestrictedDataProviderInterface
 {
     private $api;

src/DataProvider/PlaceItemDataProvider.php

@@ -10,6 +10,9 @@ use Dbp\Relay\ExampleBundle\Entity\Place;
 use Dbp\Relay\ExampleBundle\Service\PlaceProviderInterface;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
+/**
+ * This is an example of an item data provider that uses the PlaceProviderInterface to get the data for a single item.
+ */
 final class PlaceItemDataProvider extends AbstractController implements ItemDataProviderInterface, RestrictedDataProviderInterface
 {
     private $api;

src/DependencyInjection/Configuration.php

@@ -9,6 +9,9 @@ use Symfony\Component\Config\Definition\ConfigurationInterface;
 
 class Configuration implements ConfigurationInterface
 {
+    /**
+     * You can setup your configuration here.
+     */
     public function getConfigTreeBuilder(): TreeBuilder
     {
         $treeBuilder = new TreeBuilder('dbp_relay_example');

src/Service/ExternalApi.php

@@ -6,6 +6,11 @@ namespace Dbp\Relay\ExampleBundle\Service;
 
 use Dbp\Relay\ExampleBundle\Entity\Place;
 
+/**
+ * Class ExternalApi.
+ *
+ * This is an example of an external API that can be used to fetch data from an external service.
+ */
 class ExternalApi implements PlaceProviderInterface
 {
     private $places;
@@ -15,6 +20,7 @@ class ExternalApi implements PlaceProviderInterface
         // Make phpstan happy
         $service = $service;
 
+        // TODO: Fetch data from external service
         $this->places = [];
         $place1 = new Place();
         $place1->setIdentifier('graz');
@@ -43,4 +49,9 @@ class ExternalApi implements PlaceProviderInterface
     {
         return $this->places;
     }
+
+    public function storePlace(Place $place): void
+    {
+        // TODO: Store place in external service
+    }
 }

src/Service/PlaceProviderInterface.php

@@ -11,4 +11,6 @@ interface PlaceProviderInterface
     public function getPlaceById(string $identifier): ?Place;
 
     public function getPlaces(): array;
+
+    public function storePlace(Place $place): void;
 }

tests/ApiTest.php

@@ -9,6 +9,16 @@ use Symfony\Component\HttpFoundation\Response;
 
 class ApiTest extends ApiTestCase
 {
+    /**
+     * You can test some basic api functionality here.
+     *
+     * @return void
+     *
+     * @throws \Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\RedirectionExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
     public function testBasics()
     {
         $client = self::createClient();
@@ -31,6 +41,11 @@ class ApiTest extends ApiTestCase
         $this->assertSame('foo', json_decode($response->getContent(), true)['name']);
     }
 
+    /**
+     * Test if you can access the api without a user.
+     *
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
     public function testNoAuth()
     {
         $client = self::createClient();

tests/Kernel.php

@@ -47,6 +47,7 @@ class Kernel extends BaseKernel
             'secret' => '',
         ]);
 
+        // TODO: Inject settings from dbp_relay_example.yaml
         $container->extension('dbp_relay_example', [
             'example_config' => 'test-42',
         ]);