tmdinosaurcenter
/
tainacan
mirror of https://github.com/tainacan/tainacan
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documenting repositories

This commit is contained in:
Leo Germani 2019-05-12 22:03:09 -03:00
parent d21bbb3468
commit 470235f3ba
9 changed files with 1197 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/assets/entity-database.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

291
docs/generate-repo-descriptions.php Normal file
View File

@ -0,0 +1,291 @@
<?php
/**
* File used to generate docs for the repositories classes
*
* change the line below to the path to the wp-config of a WP installation
*
* Dont forget to set the language of your WordPress to english
*/
//include('/path/to/wp-config.php');
$repos = [
'collections' => [
'instance' => \Tainacan\Repositories\Collections::get_instance(),
'methods' => [
[
'name' => 'fetch',
],
[
'name' => 'fetch_one',
],
[
'name' => 'insert',
],
[
'name' => 'update',
],
[
'name' => 'delete',
],
[
'name' => 'trash',
]
]
],
'metadata' => [
'instance' => \Tainacan\Repositories\Metadata::get_instance(),
'methods' => [
[
'name' => 'fetch',
],
[
'name' => 'fetch_one',
],
[
'name' => 'fetch_ids',
],
[
'name' => 'fetch_by_collection',
],
[
'name' => 'fetch_ids_by_collection',
],
[
'name' => 'fetch_metadata_types',
],
[
'name' => 'get_core_metadata',
],
[
'name' => 'get_core_title_metadatum',
],
[
'name' => 'get_core_description_metadatum',
],
[
'name' => 'fetch_all_metadatum_values',
],
[
'name' => 'insert',
],
[
'name' => 'update',
],
[
'name' => 'delete',
],
[
'name' => 'trash',
]
]
],
'filters' => [
'instance' => \Tainacan\Repositories\Filters::get_instance(),
'methods' => [
[
'name' => 'fetch',
],
[
'name' => 'fetch_one',
],
[
'name' => 'fetch_ids',
],
[
'name' => 'fetch_by_collection',
],
[
'name' => 'fetch_ids_by_collection',
],
[
'name' => 'insert',
],
[
'name' => 'update',
],
[
'name' => 'delete',
],
[
'name' => 'trash',
]
]
],
'items' => [
'instance' => \Tainacan\Repositories\Items::get_instance(),
'methods' => [
[
'name' => 'fetch',
],
[
'name' => 'fetch_one',
],
[
'name' => 'fetch_ids',
],
[
'name' => 'get_thumbnail_id_from_document',
],
[
'name' => 'insert',
],
[
'name' => 'update',
],
[
'name' => 'delete',
],
[
'name' => 'trash',
]
]
],
'taxonomies' => [
'instance' => \Tainacan\Repositories\Taxonomies::get_instance(),
'methods' => [
[
'name' => 'fetch',
],
[
'name' => 'fetch_one',
],
[
'name' => 'fetch_by_collection',
],
[
'name' => 'term_exists',
],
[
'name' => 'insert',
],
[
'name' => 'update',
],
[
'name' => 'delete',
],
[
'name' => 'trash',
]
]
],
'terms' => [
'instance' => \Tainacan\Repositories\Terms::get_instance(),
'methods' => [
[
'name' => 'fetch',
],
[
'name' => 'fetch_one',
],
[
'name' => 'insert',
],
[
'name' => 'update',
],
[
'name' => 'delete',
],
[
'name' => 'trash',
]
]
],
// 'item-metadata' => [
// 'instance' => \Tainacan\Repositories\Item_Metadata::get_instance(),
// 'methods' => [
// [
// 'name' => 'fetch',
// ],
// [
// 'name' => 'get_value',
// ],
// [
// 'name' => 'insert',
// ],
// [
// 'name' => 'delete',
// ],
// [
// 'name' => 'trash',
// ]
// ]
// ],
];
function get_method_doc($repo, $method) {
//return '';
$r = new ReflectionMethod($repo, $method);
$doc = $r->getDocComment();
$doc = str_replace('/**', '', $doc);
$doc = str_replace('*/', '', $doc);
$doc = str_replace(' * ', '', $doc);
$doc = str_replace(' *', '', $doc);
$doc = preg_replace('/\t+/', '', $doc );
return $doc;
}
foreach ($repos as $name => $repo) {
$i = $repo['instance'];
$map = $i->get_map();
$entity = $i->entities_type;
$entity = strtolower( str_replace('\Tainacan\Entities\\', '', $entity) );
$target_file = 'repository-' . $name . '.md';
ob_start();
?>
# <?= $i->get_name(); ?> Repository
## Main Methods
These are the most used methods of this repository. For a complete list see [the repository file](../src/classes/repositories/class-tainacan-<?= $name; ?>.php).
<?php foreach ($repo['methods'] as $method): ?>
### <?= $method['name']; ?>()
<?= get_method_doc(get_class($i), $method['name']); ?>
<?php endforeach; ?>
## Usage
```PHP
$repository = \Tainacan\Repositories\<?= $i->get_name(); ?>::get_instance();
```
## Entity Properties
These are the Entity attributes for this repository. The Entity class is at [classes/entities folder](../src/classes/entities/class-tainacan-<?= $entity; ?>.php)
Property | Description | Slug | Getter | Setter | Stored as
--- | --- | --- | --- | --- | ---
<?php foreach ($map as $s => $m): ?>
<?= $m['title']; ?>|<?= $m['description']; ?>|<?= $s; ?>|`$entity->get_<?= $s; ?>()`|`$entity->set_<?= $s; ?>()`|<?= $m['map'] . "\n"; ?>
<?php endforeach; ?>
### Entity usage
Create new
```PHP
$entity = new <?= $i->entities_type; ?>();
```
Get existing by ID
```PHP
$repository = \Tainacan\Repositories\<?= $i->get_name(); ?>::get_instance();
$entity = $repository->fetch(12);
echo 'My ID is ' . $entity->get_id(); // 12
```
<?php
file_put_contents($target_file, ob_get_clean());
}

71
docs/internal-api.md
View File

@ -31,6 +31,9 @@ $metadatum->set_name('new name');
$metadatum->set_required('yes');
```
![Entities and the database](assets/entity-database.png)
Tainacan will automatically map the values of the attributes to and from where they are stored.
When you want to fetch entities from the database, this abstraction layer steps aside and let you use all the power and flexibility of `WP_Query`, which you know and love. For example:
@ -39,8 +42,16 @@ When you want to fetch entities from the database, this abstraction layer steps
Repositories\Metadata::get_instance()->fetch('s=test');
```
The `fetch` method from the repositories accept exactly the same arguments accepted by `WP_Query` and uses it internally. In fact, you could use `WP_Query` directly if you prefer, but using the repository class gives you some advantages. You dont have to know the name of the post type, you can also fetch by some mapped attribute calling it directly, withour having to use `meta_query` (or even know wether a property is stored as a post attribute or post_meta). See more details in the Fetch section below.
The `fetch` method from the repositories accept exactly the same arguments accepted by `WP_Query` and uses it internally. In fact, you could use `WP_Query` directly if you prefer, but using the repository class gives you some advantages. You dont have to know the name of the post type, you can also fetch by some mapped attribute calling it directly, without having to use `meta_query` (or even know wether a property is stored as a post attribute or post_meta). See more details in the Fetch section below.
Documentation for each repository:
* [Collections](repository-collections.md)
* [Metadata'](repository-metadata.md)
* [Filters](repository-filters.md)
* [Taxonomies](repository-taxonomies.md)
* [Items](repository-items.md)
* [Terms](repository-terms.md)
## Fetching data
@ -55,7 +66,7 @@ $collection = new Tainacan\Entities\Collection($collection_post);
$collection = new Tainacan\Entities\Collection($collection_id);
```
This will have the same effect as calling the `fetch` method from the repository passing an integer as argument. THe repository will assume it is the collection ID.
This will have the same effect as calling the `fetch` method from the repository passing an integer as argument. The repository will assume it is the collection ID.
```PHP
$collection = Tainacan\Repositories\Collections::get_instance()->fetch($collection_id);
@ -124,7 +135,7 @@ But it also can be an array of Taincan Entities objects. This is very useful whe
## Inserting
All repositories have a `insert()` method that gets an Entity as argument and save it in the database. If the entity has an ID, this method will update the entity. (yes, the same way `wp_insert_post` works)
All repositories have an `insert()` method that gets an Entity as argument and save it in the database. If the entity has an ID, this method will update the entity. (yes, the same way `wp_insert_post` works)
Each repository will get as a parameter an instace of its correspondent entity. For example, Collections repository `insert()` will get an instace of `Tainacan\Entities\Collection` and return the updated entity.
@ -166,9 +177,9 @@ Well, Item Metadata Entity is slightly different.
`Item Metada` is a special kind of entity, because it is not an actual entity itself. Rather, it is the relationship between an Item and a Field. And this relationship has a value.
So imagine a Collection of pens has a Field called "color". This means the an item of this collection will have a relationship with this metadatum, and this relation will have a value. Red, for example.
So imagine a Collection of pens has a Metadata called "color". This means that an item of this collection will have a relationship with this metadatum, and this relation will have a value. "Red", for example.
So the Item Metadata Entity constructor gets to entities: an item and a metadatum. Lets see an example, considering I alredy have a collection with metadata and an item.
So the Item Metadata Entity constructor gets two entities: an item and a metadatum. Lets see an example, considering I alredy have a collection with metadata and an item.
```PHP
// Considering $item is an existing Item Entity an $metadatum an existing Field Entity
@ -192,56 +203,6 @@ If you want to iterate over all metadata of an item or a collection, there are 2
Also, ItemMetadata Repository `fetch()` method will return an array of ItemMetadata Entities related to a given item.
### Handling Compound metadata
Compound metadata are a special type of metadata that support child metadata. It is a group of metadata.
The Compound metadatum itself does not have a value, only its children have. So when you are saving a new value for a child metadatum of a compound metadatum, it will behave as it was a normal metadatum.
However, when you save the value for the second metadatum of that same group, you must inform that it belong to that group. You do this by passing a `parent_meta_id` when initializing the Item Metada Entity. Note that you will only have this ID after you saved the first ItemMetadata of that group, because only then the group was created.
```PHP
$item_metadata1 = new \Tainacan\Entities\Item_Metadata_Entity($i, $child_field1);
$item_metadata1->set_value('Red');
if ($item_metadata1->validate()) {
$item_metadata1 = $Tainacan_Item_Metadata->insert($item_metadata1);
}
$item_metadata2 = new \Tainacan\Entities\Item_Metadata_Entity($i, $child_field2, null, $item_metadata1->get_parent_meta_id());
$item_metadata2->set_value('Blue');
if ($item_metadata2->validate()) {
$item_metadata2 = $Tainacan_Item_Metadata->insert($item_metadata2);
}
```
Now you may get the value directly from the Compound Field, and it will return an array of ItemMetadata Entities (with meta_id and parent_meta_id populated).
```PHP
$compoundItemMeta = new \Tainacan\Entities\Item_Metadata_Entity($item, $compoundField);
$compoundValue = $compoundItemMeta->get_value();
// This is an array of ItemMetadata Entities
foreach ($compoundValue as $metadatum_id => $childItemMeta) {
var_dump( $childItemMeta instanceof \Tainacan\Entities\ItemMetadataEntity ); // true
var_dump( $metadatum_id == $childItemMeta->get_field()->get_id() ); // true
echo "Value for metadatum " . $childItemMeta->get_field()->get_name() " (child of " . $compoundItemMeta->get_name() . ") is:" . $childItemMeta->get_value();
var_dump( $childItemMeta->get_field()->get_parent() == compoundItemMeta->get_field()->get_id() ); // true
var_dump( is_int($childItemMeta->get_meta_id()) && $childItemMeta->get_parent_meta_id() ); // true. they are allways set when initialized by calling get_value() on the parent ItemMetadataEntity
}
```
### More about validating
TODO: document the validation chains

122
docs/repository-collections.md Normal file
View File

@ -0,0 +1,122 @@
# Collections Repository
## Main Methods
These are the most used methods of this repository. For a complete list see [the repository file](../src/classes/repositories/class-tainacan-collections.php).
### fetch()
fetch collection based on ID or WP_Query args
Collections are stored as posts. Check WP_Query docs
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
If a number is passed to $args, it will return a \Tainacan\Entities\Collection object. But if the post is not found or
does not match the entity post type, it will return an empty array
@param array $args WP_Query args || int $args the collection id
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return \WP_Query|Array an instance of wp query OR array of entities;
### fetch_one()
Fetch one Entity based on query args.
Note: Does not work with Item_Metadata Repository
@param array $args Query Args as expected by fetch
@return false|\Tainacan\Entities The entity or false if none was found
### insert()
@param \Tainacan\Entities\Collection $collection
@return \Tainacan\Entities\Collection
{@inheritDoc}
@see \Tainacan\Repositories\Repository::insert()
### update()
### delete()
@param $collection_id
@return mixed|Collection
### trash()
@param $collection_id
@return mixed|Collection
## Usage
```PHP
$repository = \Tainacan\Repositories\Collections::get_instance();
```
## Entity Properties
These are the Entity attributes for this repository. The Entity class is at [classes/entities folder](../src/classes/entities/class-tainacan-collection.php)
Property | Description | Slug | Getter | Setter | Stored as
--- | --- | --- | --- | --- | ---
Status|The current situation of the post|status|`$entity->get_status()`|`$entity->set_status()`|post_status
ID|Unique identifier|id|`$entity->get_id()`|`$entity->set_id()`|ID
Name|The title of the collection|name|`$entity->get_name()`|`$entity->set_name()`|post_title
Author ID|The collection author's user ID (numeric string)|author_id|`$entity->get_author_id()`|`$entity->set_author_id()`|post_author
Creation Date|The collection creation date|creation_date|`$entity->get_creation_date()`|`$entity->set_creation_date()`|post_date
Modification Date|The collection modification date|modification_date|`$entity->get_modification_date()`|`$entity->set_modification_date()`|post_modified
Order|Collection order. This metadata is used if collections are manually ordered.|order|`$entity->get_order()`|`$entity->set_order()`|order
Parent Collection|Original collection from which features are inherited|parent|`$entity->get_parent()`|`$entity->set_parent()`|post_parent
Description|An introductory text describing the collection|description|`$entity->get_description()`|`$entity->set_description()`|post_content
Slug|An unique and sanitized string representation of the collection, used to build the collection URL. It must not contain any special characters or spaces.|slug|`$entity->get_slug()`|`$entity->set_slug()`|post_name
Default Order metadata|Default property items in this collections will be ordered by|default_orderby|`$entity->get_default_orderby()`|`$entity->set_default_orderby()`|meta
Default order|Default order for items in this collection. ASC or DESC|default_order|`$entity->get_default_order()`|`$entity->set_default_order()`|meta
Default Displayed Metadata|List of collection properties that will be displayed in the table view|default_displayed_metadata|`$entity->get_default_displayed_metadata()`|`$entity->set_default_displayed_metadata()`|meta
Default view mode|Collection default visualization mode|default_view_mode|`$entity->get_default_view_mode()`|`$entity->set_default_view_mode()`|meta
Enabled view modes|Which visualization modes will be available for the public to choose from|enabled_view_modes|`$entity->get_enabled_view_modes()`|`$entity->set_enabled_view_modes()`|meta
Ordination metadata|Collection metadata ordination|metadata_order|`$entity->get_metadata_order()`|`$entity->set_metadata_order()`|meta
Ordination filters|Collection filters ordination|filters_order|`$entity->get_filters_order()`|`$entity->set_filters_order()`|meta
Enable Cover Page|To use this page as the home page of this collection|enable_cover_page|`$entity->get_enable_cover_page()`|`$entity->set_enable_cover_page()`|meta
Cover Page ID|If enabled, this custom page will be used as cover for this collection, instead of default items list.|cover_page_id|`$entity->get_cover_page_id()`|`$entity->set_cover_page_id()`|meta
Header Image|The image to be used in collection header|header_image_id|`$entity->get_header_image_id()`|`$entity->set_header_image_id()`|meta
Moderators|To assign users as Moderators of this collection|moderators_ids|`$entity->get_moderators_ids()`|`$entity->set_moderators_ids()`|meta_multi
Thumbnail|Squared reduced-size version of a picture that helps recognizing and organizing files|_thumbnail_id|`$entity->get__thumbnail_id()`|`$entity->set__thumbnail_id()`|meta
Comment Status|Collection comment status: "open" means comments are allowed, "closed" means comments are not allowed.|comment_status|`$entity->get_comment_status()`|`$entity->set_comment_status()`|comment_status
Allow Items Comments|Collection items comment status: "open" means comments are allowed, "closed" means comments are not allowed.|allow_comments|`$entity->get_allow_comments()`|`$entity->set_allow_comments()`|meta
### Entity usage
Create new
```PHP
$entity = new \Tainacan\Entities\Collection();
```
Get existing by ID
```PHP
$repository = \Tainacan\Repositories\Collections::get_instance();
$entity = $repository->fetch(12);
echo 'My ID is ' . $entity->get_id(); // 12
```

149
docs/repository-filters.md Normal file
View File

@ -0,0 +1,149 @@
# Filters Repository
## Main Methods
These are the most used methods of this repository. For a complete list see [the repository file](../src/classes/repositories/class-tainacan-filters.php).
### fetch()
fetch filter based on ID or WP_Query args
Filters are stored as posts. Check WP_Query docs
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
If a number is passed to $args, it will return a \Tainacan\Entities\Filter object. But if the post is not found or
does not match the entity post type, it will return an empty array
@param array $args WP_Query args || int $args the filter id
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return \WP_Query|Array an instance of wp query OR array of entities;
### fetch_one()
Fetch one Entity based on query args.
Note: Does not work with Item_Metadata Repository
@param array $args Query Args as expected by fetch
@return false|\Tainacan\Entities The entity or false if none was found
### fetch_ids()
fetch filters IDs based on WP_Query args
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
@param array $args WP_Query args || int $args the item id
@return Array array of IDs;
@throws \Exception
### fetch_by_collection()
fetch filters by collection, searches all filters available
@param Entities\Collection $collection
@param array $args WP_Query args plus disabled_metadata
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return array Entities\Metadatum
@throws \Exception
### fetch_ids_by_collection()
fetch filters IDs by collection, considering inheritance
@param Entities\Collection|int $collection object or ID
@param array $args WP_Query args plus disabled_metadata
@return array List of metadata IDs
@throws \Exception
### insert()
@param \Tainacan\Entities\Entity $obj
@return \Tainacan\Entities\Entity | bool
@throws \Exception
### update()
### delete()
@param $filter_id
@return Entities\Filter
### trash()
@param $filter_id
@return mixed|Entities\Filter
## Usage
```PHP
$repository = \Tainacan\Repositories\Filters::get_instance();
```
## Entity Properties
These are the Entity attributes for this repository. The Entity class is at [classes/entities folder](../src/classes/entities/class-tainacan-filter.php)
Property | Description | Slug | Getter | Setter | Stored as
--- | --- | --- | --- | --- | ---
Status|Status|status|`$entity->get_status()`|`$entity->set_status()`|post_status
ID|Unique identifier|id|`$entity->get_id()`|`$entity->set_id()`|ID
Name|Name of the filter|name|`$entity->get_name()`|`$entity->set_name()`|post_title
Order|Filter order. This metadata is used if filters were manually ordered.|order|`$entity->get_order()`|`$entity->set_order()`|menu_order
Description|The filter description|description|`$entity->get_description()`|`$entity->set_description()`|post_content
Filter type options|The filter type options|filter_type_options|`$entity->get_filter_type_options()`|`$entity->set_filter_type_options()`|meta
Type|The filter type|filter_type|`$entity->get_filter_type()`|`$entity->set_filter_type()`|meta
Collection|The collection ID|collection_id|`$entity->get_collection_id()`|`$entity->set_collection_id()`|meta
Color|Filter color|color|`$entity->get_color()`|`$entity->set_color()`|meta
Metadata|Filter metadata|metadatum|`$entity->get_metadatum()`|`$entity->set_metadatum()`|meta
Max of options|The max number of options to be showed in filter sidebar.|max_options|`$entity->get_max_options()`|`$entity->set_max_options()`|meta
### Entity usage
Create new
```PHP
$entity = new \Tainacan\Entities\Filter();
```
Get existing by ID
```PHP
$repository = \Tainacan\Repositories\Filters::get_instance();
$entity = $repository->fetch(12);
echo 'My ID is ' . $entity->get_id(); // 12
```

137
docs/repository-items.md Normal file
View File

@ -0,0 +1,137 @@
# Items Repository
## Main Methods
These are the most used methods of this repository. For a complete list see [the repository file](../src/classes/repositories/class-tainacan-items.php).
### fetch()
fetch items based on ID or WP_Query args
Items are stored as posts. Check WP_Query docs
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
If a number is passed to $args, it will return a \Tainacan\Entities\Item object. But if the post is not found or
does not match the entity post type, it will return an empty array
The second paramater specifies from which collections item should be fetched.
You can pass the Collection ID or object, or an Array of IDs or collection objects
@param array $args WP_Query args || int $args the item id
@param array $collections Array Entities\Collection || Array int collections IDs || int collection id || Entities\Collection collection object
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return \WP_Query|Array|Item an instance of wp query OR array of entities OR a Item;
### fetch_one()
Fetch one Entity based on query args.
Note: Does not work with Item_Metadata Repository
@param array $args Query Args as expected by fetch
@return false|\Tainacan\Entities The entity or false if none was found
### fetch_ids()
fetch items IDs based on WP_Query args
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
The second paramater specifies from which collections item should be fetched.
You can pass the Collection ID or object, or an Array of IDs or collection objects
@param array $args WP_Query args || int $args the item id
@param array $collections Array Entities\Collection || Array int collections IDs || int collection id || Entities\Collection collection object
@return Array array of IDs;
### get_thumbnail_id_from_document()
Get a default thumbnail ID from the item document.
@param Entities\Item $item The item
@return int|null The thumbnail ID or null if it was not possible to find a thumbnail
### insert()
### update()
### delete()
@param $item_id
@return mixed|Item
### trash()
@param $item_id
@return mixed|Item
## Usage
```PHP
$repository = \Tainacan\Repositories\Items::get_instance();
```
## Entity Properties
These are the Entity attributes for this repository. The Entity class is at [classes/entities folder](../src/classes/entities/class-tainacan-item.php)
Property | Description | Slug | Getter | Setter | Stored as
--- | --- | --- | --- | --- | ---
Status|The posts status|status|`$entity->get_status()`|`$entity->set_status()`|post_status
ID|Unique identifier|id|`$entity->get_id()`|`$entity->set_id()`|ID
Title|Title of the item|title|`$entity->get_title()`|`$entity->set_title()`|post_title
Description|The item description|description|`$entity->get_description()`|`$entity->set_description()`|post_content
Collection|The collection ID|collection_id|`$entity->get_collection_id()`|`$entity->set_collection_id()`|meta
Author|The item author's user ID (numeric string)|author_id|`$entity->get_author_id()`|`$entity->set_author_id()`|post_author
Creation Date|The item creation date|creation_date|`$entity->get_creation_date()`|`$entity->set_creation_date()`|post_date
Modification Date|The item modification date|modification_date|`$entity->get_modification_date()`|`$entity->set_modification_date()`|post_modified
Term IDs|The item term IDs|terms|`$entity->get_terms()`|`$entity->set_terms()`|terms
Document Type|The document type, can be a local attachment, an external URL or a text|document_type|`$entity->get_document_type()`|`$entity->set_document_type()`|meta
Document|The document itself. An ID in case of attachment, an URL in case of link or a text in the case of text.|document|`$entity->get_document()`|`$entity->set_document()`|meta
Thumbnail|Squared reduced-size version of a picture that helps recognizing and organizing files|_thumbnail_id|`$entity->get__thumbnail_id()`|`$entity->set__thumbnail_id()`|meta
Comment Status|Item comment status: "open" means comments are allowed, "closed" means comments are not allowed.|comment_status|`$entity->get_comment_status()`|`$entity->set_comment_status()`|comment_status
### Entity usage
Create new
```PHP
$entity = new \Tainacan\Entities\Item();
```
Get existing by ID
```PHP
$repository = \Tainacan\Repositories\Items::get_instance();
$entity = $repository->fetch(12);
echo 'My ID is ' . $entity->get_id(); // 12
```

252
docs/repository-metadata.md Normal file
View File

@ -0,0 +1,252 @@
# Metadata Repository
## Main Methods
These are the most used methods of this repository. For a complete list see [the repository file](../src/classes/repositories/class-tainacan-metadata.php).
### fetch()
fetch metadatum based on ID or WP_Query args
metadatum are stored as posts. Check WP_Query docs
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
If a number is passed to $args, it will return a \Tainacan\Entities\Metadatum object. But if the post is not found or
does not match the entity post type, it will return an empty array
@param array $args WP_Query args || int $args the metadatum id
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return Entities\Metadatum|\WP_Query|Array an instance of wp query OR array of entities;
@throws \Exception
### fetch_one()
Fetch one Entity based on query args.
Note: Does not work with Item_Metadata Repository
@param array $args Query Args as expected by fetch
@return false|\Tainacan\Entities The entity or false if none was found
### fetch_ids()
fetch metadata IDs based on WP_Query args
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
@param array $args WP_Query args || int $args the item id
@return Array array of IDs;
@throws \Exception
### fetch_by_collection()
fetch metadatum by collection, considering inheritance and order
@param Entities\Collection $collection
@param array $args WP_Query args plus disabled_metadata
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return array Entities\Metadatum
@throws \Exception
### fetch_ids_by_collection()
fetch metadata IDs by collection, considering inheritance
@param Entities\Collection|int $collection object or ID
@param array $args WP_Query args plus disabled_metadata
@return array List of metadata IDs
@throws \Exception
### fetch_metadata_types()
fetch all registered metadatum type classes
Possible outputs are:
CLASS (default) - returns the Class name of of metadatum types registered
NAME - return an Array of the names of metadatum types registered
@param $output string CLASS | NAME
@return array of Entities\Metadata_Types\Metadata_Type classes path name
### get_core_metadata()
returns all core metadata from a specific collection
@param Entities\Collection $collection
@return Array|\WP_Query
@throws \Exception
### get_core_title_metadatum()
Get the Core Title Metadatum for a collection
@param Entities\Collection $collection
@return \Tainacan\Entities\Metadatum The Core Title Metadatum
@throws \Exception
### get_core_description_metadatum()
Get the Core Description Metadatum for a collection
@param Entities\Collection $collection
@return \Tainacan\Entities\Metadatum The Core Description Metadatum
@throws \Exception
### fetch_all_metadatum_values()
Return all possible values for a metadatum
Each metadata is a label with the metadatum name and the value.
If an ID, a slug or a Tainacan\Entities\Metadatum object is passed in the 'metadata' argument, it returns only one metadata, otherwise
it returns all metadata
@param int $metadatum_id The ID of the metadata to fetch values from
@param array|string $args {
Optional. Array or string of arguments.
@type mixed $collection_idThe collection ID you want to consider or null for all collections. If a collectoin is set
then only values applied to items in this collection will be returned
@type int $numberThe number of values to return (for pagination). Default empty (unlimited)
@type int $offsetThe offset (for pagination). Default 0
@type array|bool $items_filterArray in the same format used in @see \Tainacan\Repositories\Items::fetch(). It will filter the results to only return values used in the items inside this criteria. If false, it will return all values, even unused ones. Defatul [] (all items)
@type array $includeArray if ids to be included in the result. Default [] (nothing)
@type array $searchString to search. It will only return values that has this string. Default '' (nothing)
@type array $parent_idUsed by taxonomy metadata. The ID of the parent term to retrieve terms from. Default 0
* @type bool $count_itemsInclude the count of items that can be found in each value (uses $items_filter as well). Default false
*
* @type string $last_termThe last term returned when using a elasticsearch for calculates the facet.
}
@return array Array with the total number of values found. The total number of pages with the current number and the results with id and label for each value. Terms also include parent, taxonomy and number of children.
### insert()
@param \Tainacan\Entities\Metadatum $metadatum
@return \Tainacan\Entities\Metadatum
{@inheritDoc}
@see \Tainacan\Repositories\Repository::insert()
### update()
@param $object
@param $new_values
@return mixed|string|Entities\Entity
@throws \Exception
### delete()
@param $metadatum_id
@return mixed|void
@throws \Exception
### trash()
@param $metadatum_id
@return mixed|Entities\Metadatum
@throws \Exception
## Usage
```PHP
$repository = \Tainacan\Repositories\Metadata::get_instance();
```
## Entity Properties
These are the Entity attributes for this repository. The Entity class is at [classes/entities folder](../src/classes/entities/class-tainacan-metadatum.php)
Property | Description | Slug | Getter | Setter | Stored as
--- | --- | --- | --- | --- | ---
Status|Status|status|`$entity->get_status()`|`$entity->set_status()`|post_status
ID|Unique identifier|id|`$entity->get_id()`|`$entity->set_id()`|ID
Name|Name of the metadata|name|`$entity->get_name()`|`$entity->set_name()`|post_title
Slug|A unique and santized string representation of the metadata|slug|`$entity->get_slug()`|`$entity->set_slug()`|post_name
Order|Metadata order. This metadata will be used if collections were manually ordered.|order|`$entity->get_order()`|`$entity->set_order()`|menu_order
Parent|Parent metadata|parent|`$entity->get_parent()`|`$entity->set_parent()`|post_parent
Description|The metadata description|description|`$entity->get_description()`|`$entity->set_description()`|post_content
Type|The metadata type|metadata_type|`$entity->get_metadata_type()`|`$entity->set_metadata_type()`|meta
Required|The metadata is required. All items in this collection must fill this field|required|`$entity->get_required()`|`$entity->set_required()`|meta
Unique value|Metadata value should be unique accross all items in this collection|collection_key|`$entity->get_collection_key()`|`$entity->set_collection_key()`|meta
Multiple|Allow items to have more than one value for this metadatum|multiple|`$entity->get_multiple()`|`$entity->set_multiple()`|meta
Cardinality|Number of multiples possible metadata|cardinality|`$entity->get_cardinality()`|`$entity->set_cardinality()`|meta
Mask|The mask to be used in the metadata|mask|`$entity->get_mask()`|`$entity->set_mask()`|meta
Default value|The default value for the metadata|default_value|`$entity->get_default_value()`|`$entity->set_default_value()`|meta
Metadata type options|Specific options for metadata type|metadata_type_options|`$entity->get_metadata_type_options()`|`$entity->set_metadata_type_options()`|meta
Collection|The collection ID|collection_id|`$entity->get_collection_id()`|`$entity->set_collection_id()`|meta
Metadata Value Accepts Suggestions|Allow community to suggest different values for the metadata|accept_suggestion|`$entity->get_accept_suggestion()`|`$entity->set_accept_suggestion()`|meta
Relationship metadata mapping|The metadata mapping options. Metadata can be configured to match another type of data distribution.|exposer_mapping|`$entity->get_exposer_mapping()`|`$entity->set_exposer_mapping()`|meta
Display|Display by default on listing or do not display or never display.|display|`$entity->get_display()`|`$entity->set_display()`|meta
The semantic metadatum description URI|The semantic metadatum description URI like: https://schema.org/URL|semantic_uri|`$entity->get_semantic_uri()`|`$entity->set_semantic_uri()`|meta
### Entity usage
Create new
```PHP
$entity = new \Tainacan\Entities\Metadatum();
```
Get existing by ID
```PHP
$repository = \Tainacan\Repositories\Metadata::get_instance();
$entity = $repository->fetch(12);
echo 'My ID is ' . $entity->get_id(); // 12
```

126
docs/repository-taxonomies.md Normal file
View File

@ -0,0 +1,126 @@
# Taxonomies Repository
## Main Methods
These are the most used methods of this repository. For a complete list see [the repository file](../src/classes/repositories/class-tainacan-taxonomies.php).
### fetch()
fetch taxonomies based on ID or WP_Query args
Taxonomies are stored as posts. Check WP_Query docs
to learn all args accepted in the $args parameter (@see https://developer.wordpress.org/reference/classes/wp_query/)
You can also use a mapped property, such as name and description, as an argument and it will be mapped to the
appropriate WP_Query argument
If a number is passed to $args, it will return a \Tainacan\Entities\Taxonomy object. But if the post is not found or
does not match the entity post type, it will return an empty array
@param array $args WP_Query args | int $args the taxonomy id
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return \WP_Query|Array an instance of wp query OR array of entities;
### fetch_one()
Fetch one Entity based on query args.
Note: Does not work with Item_Metadata Repository
@param array $args Query Args as expected by fetch
@return false|\Tainacan\Entities The entity or false if none was found
### fetch_by_collection()
fetch taxonomies by collection, considering inheritance
@param Entities\Collection $collection
@param array $args WP_Query args plus disabled_metadata
@param string $output The desired output format (@see \Tainacan\Repositories\Repository::fetch_output() for possible values)
@return array Entities\Metadatum
@throws \Exception
### term_exists()
* Check if a term already exists
*
* @param Entities\Taxonomy $taxonomy The taxonomy object where to look for terms
* @param string $term_name The term name
* @param int|null $parent The ID of the parent term to look for children or null to look for terms in any hierarchical position. Default is null
* @param bool $return_term wether to return the term object if it exists. default is to false
*
* @return bool|WP_Term return boolean indicating if term exists. If $return_term is true and term exists, return WP_Term object
### insert()
@param Entities\Taxonomy $taxonomy
@return Entities\Entity
### update()
### delete()
### trash()
@param $taxonomy_id
@return mixed|Entities\Taxonomy
## Usage
```PHP
$repository = \Tainacan\Repositories\Taxonomies::get_instance();
```
## Entity Properties
These are the Entity attributes for this repository. The Entity class is at [classes/entities folder](../src/classes/entities/class-tainacan-taxonomy.php)
Property | Description | Slug | Getter | Setter | Stored as
--- | --- | --- | --- | --- | ---
Status|Status|status|`$entity->get_status()`|`$entity->set_status()`|post_status
ID|Unique identifier|id|`$entity->get_id()`|`$entity->set_id()`|ID
Name|Name of the taxonomy|name|`$entity->get_name()`|`$entity->set_name()`|post_title
Description|The taxonomy description|description|`$entity->get_description()`|`$entity->set_description()`|post_content
Slug|The taxonomy slug|slug|`$entity->get_slug()`|`$entity->set_slug()`|post_name
Allow insert|Allow/Deny the creation of new terms in the taxonomy|allow_insert|`$entity->get_allow_insert()`|`$entity->set_allow_insert()`|meta
Enabled for post types|Also enable this taxonomy for other WordPress post types|enabled_post_types|`$entity->get_enabled_post_types()`|`$entity->set_enabled_post_types()`|meta_multi
Collections|The IDs of collection where the taxonomy is used|collections_ids|`$entity->get_collections_ids()`|`$entity->set_collections_ids()`|meta_multi
### Entity usage
Create new
```PHP
$entity = new \Tainacan\Entities\Taxonomy();
```
Get existing by ID
```PHP
$repository = \Tainacan\Repositories\Taxonomies::get_instance();
$entity = $repository->fetch(12);
echo 'My ID is ' . $entity->get_id(); // 12
```

104
docs/repository-terms.md Normal file
View File

@ -0,0 +1,104 @@
# Terms Repository
## Main Methods
These are the most used methods of this repository. For a complete list see [the repository file](../src/classes/repositories/class-tainacan-terms.php).
### fetch()
fetch terms based on ID or get terms args
Terms are stored as WordPress regular terms. Check (@see https://developer.wordpress.org/reference/functions/get_terms/) get_terms() docs
to learn all args accepted in the $args parameter
The second paramater specifies from which taxonomies terms should be fetched.
You can pass the Taxonomy ID or object, or an Array of IDs or taxonomies objects
@param array $args WP_Query args || int $args the term id
@param array $taxonomies Array Entities\Taxonomy || Array int terms IDs || int collection id || Entities\Taxonomy taxonomy object
@return array of Entities\Term objects || Entities\Term
### fetch_one()
Fetch one Entity based on query args.
Note: Does not work with Item_Metadata Repository
@param array $args Query Args as expected by fetch
@return false|\Tainacan\Entities The entity or false if none was found
### insert()
@param Entities\Entity $term
@return Entities\Entity|Entities\Term
@throws \Exception
### update()
### delete()
@param Array $delete_args has ['term_id', 'taxonomy']
@return bool|int|mixed|\WP_Error
### trash()
@param $term_id
@return mixed|void
## Usage
```PHP
$repository = \Tainacan\Repositories\Terms::get_instance();
```
## Entity Properties
These are the Entity attributes for this repository. The Entity class is at [classes/entities folder](../src/classes/entities/class-tainacan-term.php)
Property | Description | Slug | Getter | Setter | Stored as
--- | --- | --- | --- | --- | ---
Status|Status|status|`$entity->get_status()`|`$entity->set_status()`|post_status
ID|Unique identifier|term_id|`$entity->get_term_id()`|`$entity->set_term_id()`|term_id
Name|Name of the term|name|`$entity->get_name()`|`$entity->set_name()`|name
Parent|The parent of the term|parent|`$entity->get_parent()`|`$entity->set_parent()`|parent
Description|The term description|description|`$entity->get_description()`|`$entity->set_description()`|description
Taxonomy|The term taxonomy|taxonomy|`$entity->get_taxonomy()`|`$entity->set_taxonomy()`|taxonomy
User|The term creator|user|`$entity->get_user()`|`$entity->set_user()`|termmeta
Header Image|The image to be used in term header|header_image_id|`$entity->get_header_image_id()`|`$entity->set_header_image_id()`|termmeta
Hide empty|Hide empty terms|hide_empty|`$entity->get_hide_empty()`|`$entity->set_hide_empty()`|hide_empty
### Entity usage
Create new
```PHP
$entity = new \Tainacan\Entities\Term();
```
Get existing by ID
```PHP
$repository = \Tainacan\Repositories\Terms::get_instance();
$entity = $repository->fetch(12);
echo 'My ID is ' . $entity->get_id(); // 12
```