Itemtype Class

Data manipulation methods

All content in Janitor is stored as Items of different types. You can define your own itemtypes (for customized data models) or use one of the built-in types. All item type classes extends the Itemtype class, which again extends the Model class. These together provides the data modelling, manipulation and validation functionality.

The Itemtype class provides generic ways of creating, updating and deleting your Items as well as adding any standard item properties, like tags, media, comments, prices or subscription method.

While this functionality is fully covered by the default Janitor templates and the interface components offered in the Janitor HTML (JML) class, this documentation allows you to build custom flows. The following methods should always be invoked through an instance of a type class, which provides the correct itemtype context.

Functions

Itemtype::save

Definition

Name
Itemtype::save
Syntax
Array|false = Itemtype::save( Array $action );

Description

Creates a new item and add the values POST'ed alongside the request – if values validate according to model defined in type class.

The method will look for any entities defined in the applied type class, or inherited from the Model class. If a value is passed (and it validates), it will be added to the new item.

A unique sindex value will be generated upon save, to provide a SEO-friendly id, which can be used to reference the item in URL's. Please note, that the sindex value might change when values of the item is modified at a later point.

A callback to an optional saved method is invoked after generic save has completed. To receive this callback, declare a saved method in your type class.

For completely customized save operations, the save method can be overwritten in your type class.

This is an API-method. It is designed to receive an Array of current REST parameters as it's only parameter. In addition to the REST instructions, all other values are sent as inputs via POST. The save method should only be invoked through a type class instance.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"save"
$_POST
Array Values which can sent via POST
Values
published_at
Timestamp for time of publishing
status
Status of the new item
#entity-name#
Set the value of an entity that exists in the model
$_FILES[variant]
Array File(s) to add to the item according to entity specification.
Values provided for each file
name
Name of media
tmp_name
Temp path to uploaded media file
type
Mimetype, like image/jpeg, video/mp4)
error
Only populated in case of an error

Return values

Array|false Returns an array containing the newly created item on success. False is returned if item creating fails.

One or more status messages will also be added to the message object, depending on success or failure.

Examples

Saving an item

If we fill the POST Array, to simulate a POST request to your script, like this:

$_POST["name"] = "Name of new post item"; $_POST["description"] = "Description of new post item";

Invoking the following methods, will create a new post item, with the name and description properties filled out.

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->save(["save"]);
Uploading a file on save

If the following values were present after a POST request to your script, and the path in tmp_name actually pointing to said png:

$_POST["name"] = "New post item with file"; $_POST["description"] = "Wow, I've got a file"; $_FILES["mediae"] = [ "type" => ["image/png"], "name" => ["file.png"], "tmp_name" => ["/tmp/xyz-abc"], "error" => [""] ];

Invoking the following methods, will create a new post item, with the name and description properties filled out and a file added to the general media collection.

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->save(["save"]);

Dependencies

PHP
  • foreach
  • preg_match
  • implode
  • method_exists
Janitor
  • Itemtype::saveItem
  • Itemtype::status
  • Itemtype::sindex
  • Itemtype::addMedia
  • Itemtype::addSingleMedia
  • Model::getPostedEntities
  • Model::validateList
  • Model::getModel
  • Model::getProperty
  • Query::checkDbExistence
  • Query::sql
  • Items::getItem
  • Log::addLog
  • Message::addMessage

Itemtype::update

Definition

Name
Itemtype::update
Syntax
Array|false = Itemtype::update( Array $action );

Description

Updates an item using the values POST'ed alongside the request – if values validate according to model defined in type class.

The method will look for any entities defined in the applied type class, or inherited from the Model class. If a value is passed (and it validates), it will be updated on the selected item.

If the name value is changed, a unique sindex value will be generated upon update, to provide a SEO-friendly id, which can be used to reference the item in URL's.

A callback to an optional updated method is invoked after generic update has completed. To receive this callback, declare a updated method in your type class.

For completely customized update operations, the update method can be overwritten in your type class.

This is an API-method. It is designed to receive an Array of current REST parameters as it's only parameter. In addition to the REST instructions, all other values are sent as inputs via POST. The update method should only be invoked through a type class instance.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"update"
1
item_id
$_POST
Array Values which can sent via POST
Values
published_at
Timestamp for time of publishing
#entity-name#
Set the value of an entity that exists in the model
$_FILES[variant]
Array File(s) to add to the item according to entity specification.
Values provided for each file
name
Name of media
tmp_name
Temp path to uploaded media file
type
Mimetype, like image/jpeg, video/mp4)
error
Only populated in case of an error

Return values

Array|false Returns an array containing the updated item on success. False is returned if item update fails.

One or more status messages will also be added to the message object, depending on success or failure.

Examples

Updating simple values

With the a POST request like this:

$_POST["name"] = "Updated name of post item 221"; $_POST["description"] = "Updated description of post item 221";

Invoking the following methods, will update the post item with item_id = 221, setting the name and description properties as filled out.

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->update(["update", 221]);
Uploading two files

If the following values were included in a POST request to your script, and the paths in tmp_name actually pointing to said png and jpg:

$_POST["name"] = "New post item with files"; $_POST["description"] = "Wow, I've got two files"; $_FILES["mediae"] = [ "type" => ["image/png", "image/jpeg"], "name" => ["file png", "file jpg"], "tmp_name" => ["/tmp/tests/test.png", "/tmp/tests/test.jpg"], "error" => ["", ""] ];

Invoking the following methods, will update a the post item, with the values from name and description and add the files to the general media collection.

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->update(["update", 221]);

Dependencies

PHP
  • foreach
  • preg_match
  • implode
  • method_exists
Janitor
  • Itemtype::saveItem
  • Itemtype::status
  • Itemtype::sindex
  • Itemtype::addMedia
  • Itemtype::addSingleMedia
  • Model::getPostedEntities
  • Model::validateList
  • Model::getModel
  • Model::getProperty
  • Query::checkDbExistence
  • Query::versionControl
  • Query::sql
  • Items::getItem
  • Log::addLog
  • Message::addMessage

Itemtype::status

Definition

Name
Itemtype::status
Syntax
Boolean = Itemtype::status( Array $action );

Description

All items can exist in two states: enabled or disabled. This is also referred to as the status of the item. This method allows you to change the current status of the item.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"status"
1
item_id
2
status (0 or 1)

Return values

Boolean true on successful change, false on failure.

Examples

Changing item status

To enable an item:

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->status(["status", 221, 1]);

To disable an item:

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->status(["status", 221, 0]);

Dependencies

PHP
  • count
  • isset
Janitor
  • Query::sql
  • Message::addMessage
  • Log::addLog

Itemtype::owner

Definition

Name
Itemtype::owner
Syntax
Boolean = Itemtype::owner( Array $action );

Description

Change the owner of an item. An item will always have one primary owner – use this method to change it.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"owner"
1
item_id
$_POST
Array Values which can sent via POST
Values
item_ownership
user_id for new item owner

Return values

Boolean true on successful change, false on failure

.

Examples

Changing item owner

To set owner of item 221 to user_id 5:

$_POST["item_ownership"] = 5; $IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->owner(["owner", 221]);

Dependencies

PHP
  • count
Janitor
  • Model::getPostedEntities
  • Model::getProperty
  • Query::sql
  • Log::addLog
  • Message::addMessage

Itemtype::delete

Definition

Name
Itemtype::delete
Syntax
Boolean = Itemtype::delete( Array $action );

Description

Deletes an item and all related information and assets – if this is allowed for the specified item. An item which has related subscriptions cannot be deleted.

A callback to an optional deleting method is invoked just before generic delete is executed. To receive this callback, declare a deleting method in your type class.

A callback to an optional deleted method is invoked after generic delete has completed. To receive this callback, declare a deleted method in your type class.

For completely customized delete operations, the delete method can be overwritten in your type class.

This is an API-method. It is designed to receive an Array of current REST parameters as it's only parameter. In addition to the REST instructions, all other values are sent as inputs via POST. The delete method should only be invoked through a type class instance.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"delete"
1
item_id

Return values

Boolean returns true on success, false on failure.

Examples

To delete the item with item_id = 221:

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->delete(["delete", 221]);

Dependencies

PHP
  • method_exists
Janitor
  • FileSystem::removeDirRecursively
  • Query::sql
  • Log::addLog
  • Message::addMessage

Itemtype::addTag

Definition

Name
Itemtype::addTag
Syntax
Mixed = Itemtype::addTag( Array $action );

Description

Add a tag to an item based on tag_id or string with valid tag syntax - if it has not already been added to the same item. Creates tag if it doens't already exist globally.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"addTag"
1
item_id
$_POST
Array Values which can sent via POST
Values
tags
Tag string or id

Return values

Mixed Tag data array on success, false on error (or if tag already exists on item).

Examples

Adding a tag, based on a valid tag string

If the following values were included in a POST request to your script, and the paths in tmp_name actually pointing to said png and jpg:

$_POST["tags"] = "post:My first tag";

Invoking the following methods, will add a "post:My first tag"-tag to item 221.

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->addTag(["addTag", 221]);

Dependencies

PHP
  • count
  • preg_match
  • is_numeric
  • isset
Janitor
  • Model::getPostedEntities
  • Model::validateList
  • Model::getProperty
  • Query::sql
  • Message::addMessage

Itemtype::deleteTag

Definition

Name
Itemtype::deleteTag
Syntax
Boolean = Itemtype::deleteTag( Array $action );

Description

Delete tag from item. The tag itself will not be deleted – only the association with the specified item.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"deleteTag"
1
item_id
2
tag_id

Return values

Boolean true on success, false on error.

Examples

To delete the tag with tag_id 21 from item with item_id = 221:

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->deleteTag(["deleteTag", 221, 21]);

Dependencies

PHP
  • count
  • preg_match
  • is_numeric
  • isset
Janitor
  • Query::sql
  • Query::result
  • Message::addMessage

Itemtype::upload

Definition

Name
Itemtype::upload
Syntax
Array = Itemtype::upload( Integer $item_id [, Array $_options ] );

Description

Internal upload handler with complex asset validation. The method is only uploading validated files to the private library folder. No data will be added to the database.

This method is used as the internal uploader for addMedia, addSingleMedia and other API methods in Janitor, that deals with uploading of files.

Parameters

$item_id
Integer item_id to add uploads to
$_options
Array Optional settings
Options
input_name
Name of input used for upload (Defaults to mediae)
variant
Variant to use for upload
auto_add_variant
Automatically add variant to uploads
$_FILES[variant]
Array File(s) to add to the item according to entity specification.
Values provided for each file
name
Name of media
tmp_name
Temp path to uploaded media file
type
Mimetype, like image/jpeg, video/mp4)
error
Only populated in case of an error

Return values

Array Array with successful upload values.

Examples

No examples

Dependencies

PHP
  • foreach
  • switch ... case
  • preg_match
  • filesize
  • ZipArchive
Janitor
  • Itemtype::getPostedEntities
  • Itemtype::validateList
  • Itemtype::identifyUploads
  • FileSystem::removeDirRecursively
  • FileSystem::makeDirRecursively
  • Message::addMessage
  • randomKey

Itemtype::addMedia

Definition

Name
Itemtype::addMedia
Syntax
Array|false = Itemtype::addMedia( Array $action );

Description

Upload, validate and add one or more files to item.

Subsequent uploads will be added to previously uploaded files.

This is an API-method. It is designed to receive an Array of current REST parameters as it's only parameter. In addition to the REST instructions, all other values are sent as inputs via POST. The addMedia method should only be invoked through a type class instance.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"addMedia"
1
item_id
2
variant
$_FILES[variant]
Array File(s) to add to the item according to entity specification.
Values provided for each file
name
Name of media
tmp_name
Temp path to uploaded media file
type
Mimetype, like image/jpeg, video/mp4)
error
Only populated in case of an error

Return values

Array|false Array of uploaded asset data. False on error.

Examples

No examples

Dependencies

PHP
  • count
  • foreach
Janitor
  • Itemtype::upload
  • Model::getPostedEntities
  • Query::checkDbExistence
  • Query::sql

Itemtype::addSingleMedia

Definition

Name
Itemtype::addSingleMedia
Syntax
Array|false = Itemtype::addSingleMedia( Array $action );

Description

Upload, validate and add one single files to item.

Subsequent uploads will delete previously uploaded files.

This is an API-method. It is designed to receive an Array of current REST parameters as it's only parameter. In addition to the REST instructions, all other values are sent as inputs via POST. The addSingleMedia method should only be invoked through a type class instance.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"addMedia"
1
item_id
2
variant
$_FILES[variant]
Array File to add to the item according to entity specification. On single file entities new uploads will overwrite any previous uploads.
Values provided for each file
name
Name of media
tmp_name
Temp path to uploaded media file
type
Mimetype, like image/jpeg, video/mp4)
error
Only populated in case of an error

Return values

Array|false Array of uploaded asset data. False on error.

Examples

No examples

Dependencies

PHP
  • count
Janitor
  • Itemtype::upload
  • Model::getPostedEntities
  • Query::checkDbExistence
  • Query::sql

Itemtype::deleteMedia

Definition

Name
Itemtype::deleteMedia
Syntax
Boolean = Itemtype::deleteMedia( Array $action );

Description

Delete media from item, including all images generated from this media.

This is an API-method. It is designed to receive an Array of current REST parameters as it's only parameter. In addition to the REST instructions, all other values are sent as inputs via POST. The updateMediaName method should only be invoked through a type class instance.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"deleteMedia"
1
item_id
2
variant

Return values

Boolean true if deletion succeeded, false if it failed.

Examples

No examples

Dependencies

PHP
  • count
Janitor
  • Query::sql
  • FileSystem::removeDirRecursively
  • Message::addMessage

Itemtype::updateMediaName

Definition

Name
Itemtype::updateMediaName
Syntax
Boolean = Itemtype::updateMediaName( Array $action );

Description

Update name of media using the value of name which must be POST'ed alongside the request.

This is an API-method. It is designed to receive an Array of current REST parameters as it's only parameter. In addition to the REST instructions, all other values are sent as inputs via POST. The updateMediaName method should only be invoked through a type class instance.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"updateMediaName"
1
item_id
2
variant
$_POST
Array Values which can sent via POST
Values
name
New name for media

Return values

Boolean true upon successful name update, false on failure.

Examples

Imagine that the following value was included in a POST request to your script:

$_POST["name"] = "New media name";

Invoking the following method, will update the name of media single_media for item_id 221 to New media name.

$IC = new Items(); $post_model = $IC->typeObject("post"); $post_model->updateMediaName(["updateMediaName", 221, "single_media"]);

Dependencies

PHP
  • count
Janitor
  • getPost
  • Query::sql
  • Message::addMessage

Itemtype::updateMediaOrder

Definition

Name
Itemtype::updateMediaOrder
Syntax
Boolean = Itemtype::updateMediaOrder( Array $action );

Description

Changes order of the media in a media collection.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"updateMediaOrder"
1
item_id
$_POST
Array Values which can sent via POST
Values
order
Comma separated list of media id's in desired order

Return values

Boolean true if update was successful, false on failure.

Examples

No examples

Dependencies

PHP
  • count
  • explode
Janitor
  • getPost
  • Query::sql
  • Message::addMessage

Itemtype::addComment

Definition

Name
Itemtype::addComment
Syntax
Mixed = Itemtype::addComment( Array $action );

Description

Add a user contributed comment to item. Will add the id of the current user to the comment entry.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"addComment"
1
item_id
$_POST
Array Values which can sent via POST
Values
item_comment
Comment text

Return values

Mixed Comment data array on success, false on failure.

Examples

No examples

Dependencies

PHP
  • count
  • date
Janitor
  • Query::sql
  • Query::lastInsertId
  • Model::getPostedEntities
  • Model::validateList
  • Model::getProperty
  • Items::getComments
  • Message::addMessage

Itemtype::updateComment

Definition

Name
Itemtype::updateComment
Syntax
Boolean = Itemtype::updateComment( Array $action );

Description

Update existing comment.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"updateComment"
1
item_id
2
comment_id
$_POST
Array Values which can sent via POST
Values
item_comment
Updated comment text

Return values

Boolean true on success, false on failure.

Examples

No examples

Dependencies

PHP
  • count
Janitor
  • Query::sql
  • Model::getPostedEntities
  • Model::validateList
  • Model::getProperty
  • Message::addMessage

Itemtype::deleteComment

Definition

Name
Itemtype::deleteComment
Syntax
Boolean = Itemtype::deleteComment( Array $action );

Description

Delete comment entirely.

Parameters

$action
Array of REST parameters sent in current request
Values
0
"deleteComment"
1
item_id
2
comment_id
$_POST
Array Values which can sent via POST
Values
item_comment
Updated comment text

Return values

Boolean true on success, false on failure.

Examples

No examples

Dependencies

PHP
  • count
Janitor
  • Query::sql
  • Message::addMessage