docs(db-fields): add documentation for DBField #147

docs/out/DBFields.md

@@ -3,6 +3,8 @@
 ## Retrieve all DB-fields:
 
 ```php
+        use CTApi\Requests\GroupRequest;
+        use CTApi\Requests\PersonRequest;
         use Requests\DBFieldRequest;
 
         $dbFields = DBFieldRequest::all();
@@ -80,6 +82,8 @@
 ## Retrieve single DB-field:
 
 ```php
+        use CTApi\Requests\GroupRequest;
+        use CTApi\Requests\PersonRequest;
         use Requests\DBFieldRequest;
 
         $dbField5pmName = DBFieldRequest::find(141);
@@ -95,3 +99,102 @@
         // ...
 
 ```
+
+## Read DBFields in Model
+
+To access the custom DBFields, utilize the `getDBFieldData()` method. This will provide an array where the column name of the DBField serves as the key and holds the corresponding value. Alternatively, you can use the `requestDBFields()->get()` method to retrieve a list of DBFieldValueContainers. Each container includes the key, value, and additional details from the DBField model such as name, content-type, and other relevant information. Example for **GroupInformation**:
+
+```php
+        use CTApi\Requests\GroupRequest;
+        use CTApi\Requests\PersonRequest;
+        use Requests\DBFieldRequest;
+
+        $group = GroupRequest::findOrFail(9);
+        $groupInformation = $group->getInformation();
+
+        /**
+         * Get all DB-Field keys:
+         */
+        $dbFieldKeys = $groupInformation?->getDBFieldKeys() ?? [];
+        $dbFieldKeysList = implode("; ", $dbFieldKeys);
+
+        var_dump( $dbFieldKeysList);
+        // Output: "color; 5pm_name"
+
+
+        /**
+         * Get DB-Field data:
+         */
+        $dbFieldData = "";
+        foreach ($groupInformation?->getDBFieldData() ?? [] as $dbFieldKey => $dbFieldValue) {
+            $dbFieldData .= $dbFieldKey . "=" . $dbFieldValue . "; ";
+        }
+        var_dump( $dbFieldData);
+        // Output: "color=; 5pm_name=Worship-Team; "
+
+
+        /**
+         * Get DB-Field data with DBModel
+         */
+        $dbFieldNames = "";
+
+        $dbFieldContainerList = $groupInformation?->requestDBFields()->get();
+
+        foreach ($dbFieldContainerList as $dbFieldValueContainer) {
+            // $dbFieldValueContainer is from Type "DBFieldValueContainer"
+            $dbFieldKey = $dbFieldValueContainer->getDBFieldKey();
+            $dbFieldValue = $dbFieldValueContainer->getDBFieldValue();
+            $dbField = $dbFieldValueContainer->getDBField();
+
+            $dbFieldNames .= $dbField->getName() . "; ";
+            // see: DBField-Model
+        }
+        var_dump( $dbFieldNames);
+        // Output: "color; 5pm Bezeichnung; "
+
+
+```
+
+DBFields are also existing for **Persons**:
+
+```php
+        use CTApi\Requests\GroupRequest;
+        use CTApi\Requests\PersonRequest;
+        use Requests\DBFieldRequest;
+
+        $person = PersonRequest::findOrFail(12);
+        $dbFieldContainerList = $person->requestDBFields()->get();
+        $dbFieldValueContainer = $dbFieldContainerList[0];
+
+        $key = $dbFieldValueContainer->getDBFieldKey();
+        $value = $dbFieldValueContainer->getDBFieldValue();
+
+        var_dump( $key);
+        // Output: "5pm_first_contact"
+
+        var_dump( $value);
+        // Output: "1629-06-01"
+
+
+        $dbFieldFirstContact = $dbFieldValueContainer->getDBField();
+
+        var_dump( $dbFieldFirstContact->getId());
+        // Output: 142
+
+        var_dump( $dbFieldFirstContact->getName());
+        // Output: "Erstkontakt (5pm)"
+
+        var_dump( $dbFieldFirstContact->getShorty());
+        // Output: "first_contact"
+
+        var_dump( $dbFieldFirstContact->getColumn());
+        // Output: "5pm_first_contact"
+
+        var_dump( $dbFieldFirstContact->getLength());
+        // Output: 20
+
+
+
+```
+
+Developer Tip: To associate DBFields with a model, you can easily accomplish this by implementing the HasDBFields trait.

docs/src/ressources/DBFields.md

@@ -7,3 +7,15 @@
 ## Retrieve single DB-field:
 
 {{ \Tests\Unit\Docs\DBFieldRequestTest.testGetDBField }}
+
+## Read DBFields in Model
+
+To access the custom DBFields, utilize the `getDBFieldData()` method. This will provide an array where the column name of the DBField serves as the key and holds the corresponding value. Alternatively, you can use the `requestDBFields()->get()` method to retrieve a list of DBFieldValueContainers. Each container includes the key, value, and additional details from the DBField model such as name, content-type, and other relevant information. Example for **GroupInformation**:
+
+{{ \Tests\Unit\Docs\DBFieldRequestTest.testReadGroupDBField }}
+
+DBFields are also existing for **Persons**:
+
+{{ \Tests\Unit\Docs\DBFieldRequestTest.testDBFieldsPerson }}
+
+Developer Tip: To associate DBFields with a model, you can easily accomplish this by implementing the HasDBFields trait.

src/Models/Traits/HasDBFields.php

@@ -10,7 +10,6 @@ trait HasDBFields
 {
     private array $dbFieldData = [];
 
-
     protected function appendDBField(string $dbFieldKey, $value)
     {
         $this->dbFieldData[$dbFieldKey] = $value;

tests/integration/Requests/DBFieldRequestTest.php

@@ -14,7 +14,6 @@
 
 class DBFieldRequestTest extends TestCaseAuthenticated
 {
-
     public function testRequestAll()
     {
         $dbFields = DBFieldRequest::all();

tests/unit/Docs/DBFieldRequestTest.php

@@ -4,8 +4,9 @@
 namespace Tests\Unit\Docs;
 
 
+use CTApi\Requests\GroupRequest;
+use CTApi\Requests\PersonRequest;
 use Requests\DBFieldRequest;
-use Tests\Integration\TestCaseAuthenticated;
 use Tests\Unit\TestCaseHttpMocked;
 
 class DBFieldRequestTest extends TestCaseHttpMocked
@@ -49,4 +50,67 @@ public function testGetDBField()
         $this->assertEquals("5pm Bezeichnung", $dbField5pmName->getName());
         // ...
     }
+
+    public function testReadGroupDBField()
+    {
+        $group = GroupRequest::findOrFail(9);
+        $groupInformation = $group->getInformation();
+
+        /**
+         * Get all DB-Field keys:
+         */
+        $dbFieldKeys = $groupInformation?->getDBFieldKeys() ?? [];
+        $dbFieldKeysList = implode("; ", $dbFieldKeys);
+
+        $this->assertEquals("color; 5pm_name", $dbFieldKeysList);
+
+        /**
+         * Get DB-Field data:
+         */
+        $dbFieldData = "";
+        foreach ($groupInformation?->getDBFieldData() ?? [] as $dbFieldKey => $dbFieldValue) {
+            $dbFieldData .= $dbFieldKey . "=" . $dbFieldValue . "; ";
+        }
+        $this->assertEquals("color=; 5pm_name=Worship-Team; ", $dbFieldData);
+
+        /**
+         * Get DB-Field data with DBModel
+         */
+        $dbFieldNames = "";
+
+        $dbFieldContainerList = $groupInformation?->requestDBFields()->get();
+
+        foreach ($dbFieldContainerList as $dbFieldValueContainer) {
+            // $dbFieldValueContainer is from Type "DBFieldValueContainer"
+            $dbFieldKey = $dbFieldValueContainer->getDBFieldKey();
+            $dbFieldValue = $dbFieldValueContainer->getDBFieldValue();
+            $dbField = $dbFieldValueContainer->getDBField();
+
+            $dbFieldNames .= $dbField->getName() . "; ";
+            // see: DBField-Model
+        }
+        $this->assertEquals("color; 5pm Bezeichnung; ", $dbFieldNames);
+    }
+
+    public function testDBFieldsPerson()
+    {
+        $person = PersonRequest::findOrFail(12);
+        $dbFieldContainerList = $person->requestDBFields()->get();
+        $dbFieldValueContainer = $dbFieldContainerList[0];
+
+        $key = $dbFieldValueContainer->getDBFieldKey();
+        $value = $dbFieldValueContainer->getDBFieldValue();
+
+        $this->assertEquals("5pm_first_contact", $key);
+        $this->assertEquals("1629-06-01", $value);
+
+        $dbFieldFirstContact = $dbFieldValueContainer->getDBField();
+
+        $this->assertEquals(142, $dbFieldFirstContact->getId());
+        $this->assertEquals("Erstkontakt (5pm)", $dbFieldFirstContact->getName());
+        $this->assertEquals("first_contact", $dbFieldFirstContact->getShorty());
+        $this->assertEquals("5pm_first_contact", $dbFieldFirstContact->getColumn());
+        $this->assertEquals(20, $dbFieldFirstContact->getLength());
+
+    }
 }

tests/unit/HttpMock/data/api_dbfields.json

@@ -27,6 +27,62 @@
       "hideInFrontend": false,
       "notConfigurable": false,
       "isBasicInfo": false
+    },
+    {
+      "id": 142,
+      "name": "Erstkontakt (5pm)",
+      "shorty": "first_contact",
+      "column": "5pm_first_contact",
+      "length": 20,
+      "fieldCategory": {
+        "id": 2,
+        "name": "information",
+        "internCode": "f_church",
+        "table": "cdb_person"
+      },
+      "fieldType": {
+        "id": 3,
+        "name": "Datumsfeld",
+        "internCode": "date"
+      },
+      "isActive": true,
+      "isNewPersonField": false,
+      "lineEnding": "",
+      "securityLevel": 1,
+      "sortKey": 0,
+      "deleteOnArchive": false,
+      "nullable": true,
+      "hideInFrontend": false,
+      "notConfigurable": false,
+      "isBasicInfo": false
+    },
+    {
+      "id": 134,
+      "name": "color",
+      "shorty": "color",
+      "column": "color",
+      "length": 20,
+      "fieldCategory": {
+        "id": 4,
+        "name": "group",
+        "internCode": "f_group",
+        "table": "cdb_gruppe"
+      },
+      "fieldType": {
+        "id": 1,
+        "name": "Textfeld",
+        "internCode": "text"
+      },
+      "isActive": true,
+      "isNewPersonField": false,
+      "lineEnding": "<br\/>",
+      "securityLevel": 1,
+      "sortKey": 400,
+      "deleteOnArchive": false,
+      "nullable": true,
+      "hideInFrontend": true,
+      "notConfigurable": false,
+      "isBasicInfo": true
     }
   ]
 }