Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

YOrm Erläuterungen zu Collection-, Query- und Dataset-Methoden #1459

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

YOrm Erläuterungen zu Collection-, Query- und Dataset-Methoden #1459

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
237 changes: 117 additions & 120 deletions docs/04_yorm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -401,107 +401,113 @@ echo $post->executeForm($yform)

<a name="collection-methoden"></a>

### collection-Methoden

- delete
- executeForm
- filter
- first
- getForm
- getIds
- getTable
- getTableName
- getUniqueValue
- getValues
- groupBy
- isEmpty
- isValid
- isValueUnique
- last
- map
- populateRelation
- save
- setData
- setValue
- shuffle
- slice
- sort
- split
- toKeyIndex
- toKeyValue
Die Klasse `rex_yform_manager_collection` stellt eine Reihe von Methoden zur Verfügung, um mit Sammlungen von Datensätzen zu arbeiten. Hier sind einige der wichtigsten Methoden:

- `chunk()`: Teilt die Sammlung in Chunks einer bestimmten Größe.
- `delete()`: Löscht alle Datensätze in der Sammlung.
- `executeForm()`: Führt ein Formular für alle Datensätze in der Sammlung aus.
- `filter()`: Filtert die Sammlung nach einer bestimmten Bedingung.
- `first()`: Gibt den ersten Datensatz in der Sammlung zurück.
- `getForm()`: Gibt ein Formular für die Sammlung zurück.
- `getIds()`: Gibt die IDs aller Datensätze in der Sammlung zurück.
- `getTable()`: Gibt die Tabelle zurück, zu der die Sammlung gehört.
- `getTableName()`: Gibt den Namen der Tabelle zurück, zu der die Sammlung gehört.
- `getUniqueValue()`: Gibt einen eindeutigen Wert für die Sammlung zurück.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Der Satz klingt für mich, als würde die Methode eine Art Hash für die gesamte Sammlung liefern.
Tatsächlich übergibt man aber einen Feldnamen an die Methode, und die Methode prüft dann, ob der Wert in dem Feld bei allen Elementen der Sammlung gleich ist. Wenn ja, wird der Wert geliefert, ansonsten null.

Selbst benötigt man die Methode eher nicht. Sie wird genutzt, wenn man mehrere Datensätze gleichzeitig bearbeitet. Für die Entscheidung, ob in dem jeweiligen Formularfeld ein Wert initial gesetzt wird (weil für alle Datensätze gleich) oder ob das Feld leer gelassen wird (weil unterschiedliche Werte).

Weiß nicht, wie man es in einem Satz besser beschreiben kann.

- `getValues()`: Gibt die Werte aller Datensätze in der Sammlung zurück.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Zu einem bestimmten Key. Also die Werte eine Spalte.

- `groupBy()`: Gruppiert die Sammlung nach einem bestimmten Feld.
- `implode()`: Fügt die Werte aller Datensätze in der Sammlung zu einem String zusammen.
- `isEmpty()`: Überprüft, ob die Sammlung leer ist.
- `isValid()`: Überprüft, ob alle Datensätze in der Sammlung gültig sind.
- `isValueUnique()`: Überprüft, ob ein bestimmter Wert in der Sammlung eindeutig ist.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Die Methode gehört mit zu getUniqueValue (siehe oben, wird intern in getUniqueValue genutzt für den Check). Die Beschreibung hier passt aber denke ich so.

- `last()`: Gibt den letzten Datensatz in der Sammlung zurück.
- `map()`: Wendet eine Funktion auf alle Datensätze in der Sammlung an.
- `populateRelation()`: Füllt ein Relationsfeld für alle Datensätze in der Sammlung.
- `save()`: Speichert alle Datensätze in der Sammlung.
- `setData()`: Lädt Daten in alle Datensätze in der Sammlung.
Copy link
Member

@gharlan gharlan Dec 5, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das passt nicht, glaube ich. Man tauscht damit eher die Datensätze in der Sammlung aus. Man hat danach also eine Collection mit den an setData übergebenen Datensätzen. Die vorherigen Datensätze bleiben unberührt, sind nur nicht mehr in dem Collection-Objekt.
(Ist mehr eine interne Methode)

- `setValue()`: Setzt einen Wert für alle Datensätze in der Sammlung.
- `shuffle()`: Mischelt die Datensätze in der Sammlung.
- `slice()`: Gibt einen Teil der Datensätze in der Sammlung zurück.
- `sort()`: Sortiert die Datensätze in der Sammlung.
- `split()`: Teilt die Sammlung in zwei Teile
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nicht in zwei Teile, sondern in die gewünschte Anzahl. split(5) würde also 5 Teile liefern.

- `toKeyIndex()`: Gibt die Datensätze in der Sammlung als Array zurück, wobei die IDs der Datensätze als Schlüssel verwendet werden.
- `toKeyValue()`: Gibt die Datensätze in der Sammlung als Array zurück, wobei die Werte eines bestimmten Feldes als Schlüssel und die Werte eines anderen Feldes als Werte verwendet werden.

<a name="query-methoden"></a>

### query-Methoden

Die Klasse `rex_yform_manager_query` stellt eine Reihe von Methoden zur Verfügung, um Abfragen zu erstellen. Hier sind einige der wichtigsten Methoden:

- Alias
- alias
- getTableAlias
- count
- exists (liefert true oder false zurück. Optimal für große Abfragen.)
- `alias()`: Setzt den Alias für die Tabelle, auf die sich die Abfrage bezieht.
- `getTableAlias()`: Gibt den Alias für die Tabelle, auf die sich die Abfrage bezieht, zurück. Wenn kein Alias gesetzt ist, wird der Tabellenname zurückgegeben.
- `count()`: Gibt die Anzahl der Datensätze zurück, die von der Abfrage zurückgegeben werden.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das passt grob. Wobei das eine separate Query absetzt. Man sollte es also nur nutzen, wenn man nur die Anzahl braucht. Braucht man anschließend auch die Datensätze, sollte man eher erst die Collection per find() holen, und dort dann per count() die Anzahl ermitteln.

- `exists()`: Überprüft, ob die Abfrage mindestens einen Datensatz zurückgibt. (Optimal für große Abfragen.)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auch hier ist es eine separate Query. Daher sollte man die auch nur nutzen, wenn einen nur interessiert, ob die Query mindestens einen Datensatz liefern würde.

- Find
- find
- findId
- findIds
- findOne (liefert einen Datensatz als Objekt zurück.)
- `find()`: Gibt eine Sammlung (Collection) von Datensätzen zurück, die von der Abfrage zurückgegeben werden.
- `findId()`: Gibt die ID des ersten Datensatzes zurück, der von der Abfrage zurückgegeben wird.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das stimmt nicht, es wird der Datensatz zu der übergebenen ID geliefert.

- `findIds()`: Gibt die IDs aller Datensätze zurück, die von der Abfrage zurückgegeben werden.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Entsprechend werden hier die Datensätze zu den übergebenen IDs geliefert.

- `findOne()`: Gibt den ersten Datensatz als Dataset zurück, der von der Abfrage zurückgegeben wird.
- Get
- get
- getAll
- Group By
- groupBy
- groupByRaw
- resetGroupBy
- Join
- joinRaw
- joinRelation
- joinType
- joinTypeRelation
- leftJoin
- leftJoinRelation
- resetJoins
- Limit
- limit
- resetLimit
- Order By
- orderBy
- orderByRaw
- resetOrderBy
- paginate ([Beispiel](#beispiel-paginate))
- `get()`: Gibt eine Sammlung (Collection) von Datensätzen zurück, die von der Abfrage zurückgegeben werden.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

get ist eine statische Methode und liefert/erzeugt das query-objekt: rex_yform_manager_query::get($table)

- `getAll()`: Gibt alle Datensätze zurück, die von der Abfrage zurückgegeben werden.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Die Methode gibt es nicht in der Query-Klasse (aber in der dataset-Klasse).

- Group By (Entspricht `GROUP BY` in SQL.)
- `groupBy()`: Gruppiert die Abfrage nach einem bestimmten Feld.
- `groupByRaw()`: Gruppiert die Abfrage nach einem bestimmten Feld, wobei die Feldnamen nicht zitiert werden.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Es wird eher nach einer beliebigen SQL-Expression gruppiert, muss kein Feld sein.
"zitiert" passt nicht als Übersetzung, denke ich. Eher "escapet" oder "maskiert" oder so.

Gilt entsprechend auch bei allen anderen *Raw-Methoden.

- `resetGroupBy()`: Setzt die Gruppierung der Abfrage zurück.
- Join (Entspricht `JOIN` in SQL)
- `join()`: Fügt der Abfrage einen Join hinzu.
- `joinRaw()`: Fügt der Abfrage einen Join hinzu, wobei die Feldnamen nicht zitiert werden.
- `joinRelation()`: Fügt der Abfrage einen Join hinzu, der auf einem Relationsfeld basiert.
- `joinType()`: Setzt den Join-Typ für die Abfrage.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das ist eher die Basis-Methode, die von join und leftJoin aufgerufen wird.
Die Methode fügt also auch einen Join hinzu, wobei man hier den Join-Type mit angeben kann (INNER/LEFT/RIGHT...).

Entsprechend bei joinTypeRelation.

- `joinTypeRelation()`: Setzt den Join-Typ für die Abfrage, der auf einem Relationsfeld basiert.
- `leftJoin()`: Fügt der Abfrage einen Left Join hinzu.
- `leftJoinRelation()`: Fügt der Abfrage einen Left Join hinzu, der auf einem Relationsfeld basiert.
- `resetJoins()`: Setzt alle Joins der Abfrage zurück.
- Limit (Entspricht `LIMIT` in SQL.)
- `limit()`: Setzt das Limit für die Abfrage.
- `resetLimit()`: Setzt das Limit der Abfrage zurück.
- Order By (Entspricht `ORDER BY` in SQL.)
- `orderBy()`: Setzt die Sortierreihenfolge für die Abfrage.
- `orderByRaw()`: Setzt die Sortierreihenfolge für die Abfrage, wobei die Feldnamen nicht zitiert werden.
- `resetOrderBy()`: Setzt die Sortierreihenfolge der Abfrage zurück.
- Paginate ([Beispiel](#beispiel-paginate))
- Query
- query
- queryOne
- save
- Select
- resetSelect
- select
- selectRaw (lässt individuelle Argumente zu, wie z. B. `CONCAT, SUM`)
- `query()`: Führt die Abfrage aus und gibt ein `rex_yform_manager_query` Objekt zurück.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das ist eine Methode aus der Dataset-Klasse, nicht aus der Query-Klasse.
Die Methode erzeugt nur das Query-Objekt.

- `queryOne()`: Führt die Abfrage aus und gibt ein `rex_yform_manager_query` Objekt für den ersten Datensatz zurück.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das ist eine Methode aus der Dataset-Klasse, nicht aus der Query-Klasse.
Die Methode braucht man selbst nur, wenn man ein Dataset-Objekt aus einer Query als String erzeugen will. Also wenn man gerade ohne die Query-Klasse arbeiten will. Sie liefert also auch kein Query-Objekt.

Dazu passend gibt es auch noch queryCollection.

- Save (Entspricht `INSERT` oder `UPDATE` in SQL.)
- `save()`: Speichert die Daten, die der Abfrage hinzugefügt wurden.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gibt es in der Query-Klasse nicht.

- Select (Entspricht `SELECT` in SQL.)
- `resetSelect()`: Setzt die Felder zurück, die von der Abfrage zurückgegeben werden.
- `select()`: Setzt die Felder, die von der Abfrage zurückgegeben werden.
- `selectRaw()`: Setzt die Felder, die von der Abfrage zurückgegeben werden, wobei die Feldnamen nicht zitiert werden. (lässt individuelle Argumente zu, wie z. B. `CONCAT, SUM`)
- Table
- getTable
- getTableName
- Where
- resetWhere
- setWhereOperator
- where
- whereNot
- whereNull
- whereNotNull
- whereBetween
- whereNotBetween
- whereNested
- whereRaw
- whereListContains
- `getTable()`: Gibt ein `rex_yform_manager_table` Objekt für die Tabelle zurück, auf die sich die Abfrage bezieht.
- `getTableName()`: Gibt den Namen der Tabelle zurück, auf die sich die Abfrage bezieht.
- Where (Entspricht `WHERE` in SQL.)
- `resetWhere()`: Setzt die WHERE-Bedingung der Abfrage zurück.
- `setWhereOperator()`: Setzt den Operator für die WHERE-Bedingung der Abfrage.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also wie die where-Bedingungen verknüpft werden (AND oder OR).

- `where()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu.
- `whereBetween()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, die auf einem Bereich von Werten basiert.
- `whereListContains()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, die auf einer Liste von Werten basiert.
- `whereNested()`: Fügt der WHERE-Bedingung der Abfrage eine verschachtelte Bedingung hinzu.
- `whereNot()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, die auf dem Gegenteil eines Wertes basiert.
- `whereNotBetween()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, die auf dem Gegenteil eines Bereichs von Werten basiert.
- `whereNull()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, die auf einem NULL-Wert basiert.
- `whereNotNull()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, die auf einem nicht NULL-Wert basiert.
- `whereRaw()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, wobei die Feldnamen nicht zitiert werden.
- `whereListContains()`: Fügt der WHERE-Bedingung der Abfrage eine Bedingung hinzu, die auf einer Liste von Werten basiert.
- Having
- resetHaving
- setHavingOperator
- having
- havingNot
- havingNull
- havingNotNull
- havingBetween
- havingNotBetween
- havingRaw
- havingListContains

- `resetHaving()`: Setzt die HAVING-Bedingung der Abfrage zurück.
- `setHavingOperator()`: Setzt den Operator für die HAVING-Bedingung der Abfrage.
- `having()`: Fügt der HAVING-Bedingung der Abfrage eine Bedingung hinzu.
- `havingBetween()`: Fügt der HAVING-Bedingung der Abfrage eine Bedingung hinzu, die auf einem Bereich von Werten basiert.
- `havingNotBetween()`: Fügt der HAVING-Bedingung der Abfrage eine Bedingung hinzu, die auf dem Gegenteil eines Bereichs von Werten basiert.
- `havingNull()`: Fügt der HAVING-Bedingung der Abfrage eine Bedingung hinzu, die auf einem NULL-Wert basiert.
- `havingNotNull()`: Fügt der HAVING-Bedingung der Abfrage eine Bedingung hinzu, die auf einem nicht NULL-Wert basiert.
- `havingRaw()`: Fügt der HAVING-Bedingung der Abfrage eine Bedingung hinzu, wobei die Feldnamen nicht zitiert werden.
- `havingListContains()`: Fügt der HAVING-Bedingung der Abfrage eine Bedingung hinzu, die auf einer Liste von Werten basiert.

Beispiel für whereListContains

```php
Expand All @@ -514,39 +520,31 @@ $query->whereListContains('my_column', 'my_value');
$query->whereListContains('my_column', [3, 5, 9]);
```

Beispiel für resetSelect()

// resetSelect() ermöglicht es im Anschluss per select nur die Felder des Datensatzes zu erhalten, die man wirklich benötigt.

```php
$dataset = rex_yform_manager_query::get('rex_yf_example')
->resetSelect()
->select('id')
->select('title')
->select('name')
->findId($id);
```

<a name="dataset-methoden"></a>

### dataset-Methoden

- create
- get
- getAll
- getData (liefert Felder als Array zurück)
- getForm (liefert Formular zurück - EXPERIMENTELL!)
- getId
- getMessages
- getRaw
- getRelatedCollection
- getRelatedDataset
- getTable
- getTableName
- getValue
- hasValue
- isValid
- loadData
Die Klasse `rex_yform_manager_dataset` stellt eine Reihe von Methoden zur Verfügung, um mit Datensätzen zu arbeiten. Hier sind einige der wichtigsten Methoden:

- `create($table, array $data = [])`: Erstellt einen neuen Datensatz in der angegebenen Tabelle und gibt ein `rex_yform_manager_dataset` Objekt für diesen Datensatz zurück.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wirklich erstellt wird der Datensatz erst, wenn man danach dann save() aufruft.
Vielleicht aber trotzdem ok so die Beschreibung.

- `get($table, $id)`: Gibt ein `rex_yform_manager_dataset` Objekt für den Datensatz mit der angegebenen ID in der angegebenen Tabelle zurück.
- `getAll($table, $where = null, array $orderBy = [])`: Gibt alle Datensätze in der angegebenen Tabelle als Array von `rex_yform_manager_dataset` Objekten zurück. Optional kann eine WHERE-Bedingung und eine Sortierreihenfolge angegeben werden.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nicht als Array, sondern als Collection-Objekt.
Where und Sortierung können nicht angegeben werden.

- `getData()`: Gibt die Daten des aktuellen Datensatzes als assoziatives Array zurück.
- `getForm()`: Gibt ein YForm-Formular für den aktuellen Datensatz zurück. (EXPERIMENTELL)
- `getId()`: Gibt die ID des aktuellen Datensatzes zurück.
- `getMessages()`: Gibt eine Liste der Fehlermeldungen zurück, die beim letzten Speichern des aktuellen Datensatzes aufgetreten sind.
- `getRaw()`: Gibt die Rohdaten des aktuellen Datensatzes als assoziatives Array zurück.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das passt nicht. Die Methode ist ähnlich wie get($id), liefert also ein Dataset-Objekt.
Aber anders als get() ruft getRaw den Datensatz noch gar nicht ab, und prüft auch nicht, ob die ID überhaupt existiert.
Wird mehr für interne Zwecke benötigt.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bzw. man kann es auch nutzen, um einem neuen Datensatz eine fixe ID zu vergeben. Also ::getRaw($id) statt ::create().

- `getRelatedCollection($field)`: Gibt eine `rex_yform_manager_collection` aller Datensätze zurück, die mit dem aktuellen Datensatz über das angegebene Relationsfeld verknüpft sind.
- `getRelatedDataset($field)`: Gibt ein `rex_yform_manager_dataset` Objekt für den Datensatz zurück, der mit dem aktuellen Datensatz über das angegebene Relationsfeld verknüpft ist.
- `getTable()`: Gibt ein `rex_yform_manager_table` Objekt für die Tabelle zurück, zu der der aktuelle Datensatz gehört.
- `getTableName()`: Gibt den Namen der Tabelle zurück, zu der der aktuelle Datensatz gehört.
- `getValue($field)`: Gibt den Wert eines Feldes im aktuellen Datensatz zurück.
- `hasValue($field)`: Überprüft, ob ein Feld im aktuellen Datensatz einen Wert hat.
- `setValue($field, $value)`: Setzt den Wert eines Feldes im aktuellen Datensatz.
- `isValid()`: Überprüft, ob der aktuelle Datensatz gültig ist.
- `loadData($data)`: Lädt Daten in den aktuellen Datensatz.
- `delete()`: Löscht den aktuellen Datensatz.
- `save()`: Speichert Änderungen am aktuellen Datensatz.

<a name="debugging"></a>

Expand Down Expand Up @@ -585,7 +583,6 @@ Datei `/redaxo/src/addons/yform/plugins/manager/lib/yform/manager/dataset.php` u

<a name="dataset-yform"></a>


### Dataset als YForm-Formular editieren / absenden

```php
Expand Down
Loading