Documentation

IFolder extends IFolderActions, IFolderContent

This interface provides elementary getter and setter methods for folder objects. All folder types (Folder, Collection, Gallery, ...) have implemented this interface.

Also the root ("Unorganized") is a folder and implements this interface. Usually, the root acts as "-1" but you should use the _wp_rml_root function to get the root id. If this interface does not provide an expected method, yet, have a look at the other API files. For example to create a folder use wp_rml_create.

Check if a variable is surely a IFolder interface object:

$folder = wp_rml_get_object_by_id(5);
if (is_rml_folder($folder)) {
     // It is an interface implementation of IFolder
}

Register own folder type:

You can create your own implementation of a folder type (Gallery, Collection, Root, ...) just have a look at the wp-content/plugins/real-media-library/inc/folder files.

Also have a look at the wp_rml_register_creatable function to register your class (RML_TYPE_FOLDER is an unique defined integer for your folder type):

wp_rml_register_creatable(Folder::class, RML_TYPE_FOLDER);
Tags
see
wp_rml_root_childs
see
wp_rml_get_object_by_id
see
wp_rml_get_by_id
see
wp_rml_get_by_absolute_path
see
wp_rml_objects
see
is_rml_folder
see
IFolderActions

Table of Contents

Methods

anyChildrenHas()  : array<string|int, mixed>
Get all children which meets a given column value or column value is not empty.
anyChildrenHasMetadata()  : array<string|int, mixed>
Get all chilren which meets a given meta key value or meta key value is not empty.
anyParentHas()  : array<string|int, mixed>
Get all parents which meets a given column value or column value is not empty.
anyParentHasMetadata()  : array<string|int, mixed>
Get all parents which meets a given meta key value or meta key value is not empty.
contentDeleteOrder()  : bool
(Pro only) Deletes the complete order for this folder.
contentEnableOrder()  : bool
(Pro only) Enable the order functionality for this folder.
contentIndex()  : bool
(Pro only) Index the order table.
contentOrder()  : true
(Pro only) See API function for more information.
contentOrderBy()  : bool
(Pro only) Start to order the given folder content by a given order type.
contentReindex()  : bool
(Pro only) This function retrieves the order of the order table and removes empty spaces, for example: <pre>0 1 5 7 8 9 10 => 0 1 2 3 4 5 6</pre>
contentRestoreOldCustomNr()  : bool
(Pro only) Restore the current order number to the old custom order number.
forceContentCustomOrder()  : bool
Override this functionality to force the content custom order in the posts_clauses.
getAbsolutePath()  : string
Creates a absolute path. If the absolute path is empty or forced to, it will be updated in the database, too.
getAllowedChildrenTypes()  : bool|array<string|int, int>
Get all allowed children folder types.
getAllParents()  : array<string|int, int>
Get all parents of this folder.
getAttachmentNextTo()  : array<string|int, mixed>
(Pro only) Get the next attachment row for a specific attachment. It returns false if the attachment is at the end or the folder has no custom content order.
getChildren()  : IFolder
Get children of this folder.
getCnt()  : int
Gets the count of the files in this folder.
getContentAggregationNr()  : int
(Pro only) Gets the biggest order number;
getContentCustomOrder()  : int
The content custom order defines the state of the content order functionality:
getContentNrOf()  : int|bool
(Pro only) Get the order number for a specific attachment in this folder.
getContentOldCustomNrCount()  : int
(Pro only) Get the old custom order number count so we can decide if already available.
getId()  : int
Get the folder id.
getMaxOrder()  : int
Get the maximal order number of the children.
getName()  : string
Get the folder name.
getOrder()  : int
Get the order number.
getOwner()  : int
Get the creator/owner of the folder.
getParent()  : int
Get the parent folder id.
getPath()  : string
Creates a absolute path without slugging' the names.
getPlain()  : array<string|int, mixed>
Gets a plain array with folder properties.
getRestrictions()  : array<string|int, string>
Get the restrictions of this folder.
getRestrictionsCount()  : int
Get the count of the restrictions.
getRowData()  : mixed
Get the full row of the SQL query.
getSlug()  : string
Returns a sanitized title for the folder. If the slug is empty or forced to, it will be updated in the database, too.
getType()  : int
Return the type for the given folder. For example: 0 = Folder, 1 = Collection, 2 = Gallery
getTypeDescription()  : string
Get the type description for this folder.
getTypeName()  : string
Get the type name for this folder. For example: Folder, Collection, Gallery, Unorganized.
hasChildren()  : bool
Checks if this folder has a children with a given name.
insert()  : true
Insert an amount of post ID's (attachments) to this folder.
is()  : bool
Check if the folder object is a given type.
isContentCustomOrderAllowed()  : bool
Checks if the folder is allowed to use custom content order.
isRestrictFor()  : bool
Checks if this folder has a special restriction.
isValidChildrenType()  : bool
Checks if a given folder type is allowed in this folder.
isVisible()  : bool
Check if the folder object is visible to the user.
orderSubfolders()  : bool
(Pro only) Start to order the given folder subfolders by a given order type.
postsClauses()  : bool
Override the default posts_clauses join and orderby instead of the RML standard.
read()  : array<string|int, int>
Fetch all attachment ids currently in this folder. It uses the default WP_Query to fetch the ids. You can also use the WP_Query like: ```php $query = new \WP_Query([ 'post_status' => 'inherit', 'post_type' => 'attachment', 'rml_folder' => 4, // Can also be an array of integers 'rml_include_children' => false // (optional) Include files of subfolder, you have to use wp_rml_all_children_sql_supported(false, 'function') for checking support ]); ```
reindexChildrens()  : bool
(Pro only) Reindex the children folders so the "ord" number is set right.
relocate()  : bool|array<string|int, string>
Relocate a folder to a given place in the folder structure.
resetSubfolderOrder()  : bool
(Pro only) Reset the subfolders order'.
setName()  : bool
Renames a folder and then checks, if there is no duplicate folder in the parent folder.
setParent()  : bool
Changes the parent folder of this folder.
setRestrictions()  : bool
Set restrictions for this folder. Allowed restrictions for folders:
setVisible()  : mixed
Sets the folders visibility to the user.
updateThisAndChildrensAbsolutePath()  : mixed
Iterate all children of this folder recursively and update the absolute path. Use this function with caution because it can be time intensive.

Methods

anyChildrenHas()

Get all children which meets a given column value or column value is not empty.

public anyChildrenHas(string $column[, mixed $value = null ][, string $valueFormat = '%s' ][, bool $includeSelf = false ]) : array<string|int, mixed>
Parameters
$column : string

The column name for the wp_realmedialibrary SQL table. "slug", "name", "absolutePath", ... This string is not escaped when you pass it through this function

$value : mixed = null

The value the column should have

$valueFormat : string = '%s'

The value format for $value ($wpdb->prepare) This string is not escaped when you pass it through this function

$includeSelf : bool = false

Set true to add self to list

Tags
since
3.3
Return values
array<string|int, mixed>

folderId => columnValue, first id is the first found child

anyChildrenHasMetadata()

Get all chilren which meets a given meta key value or meta key value is not empty.

public anyChildrenHasMetadata(string $meta_key[, mixed $meta_value = null ][, string $valueFormat = '%s' ][, bool $includeSelf = false ]) : array<string|int, mixed>
Parameters
$meta_key : string

The meta key name for the wp_realmedialibrary_meta SQL table. This string is not escaped when you pass it through this function

$meta_value : mixed = null

The value the meta key should have

$valueFormat : string = '%s'

The value format for $value ($wpdb->prepare) This string is not escaped when you pass it through this function

$includeSelf : bool = false

Set true to add self to list

Tags
since
3.3
Return values
array<string|int, mixed>

Array with keys: id (meta_id), folderId, value (meta_value), first id is the first found child

anyParentHas()

Get all parents which meets a given column value or column value is not empty.

public anyParentHas(string $column[, mixed $value = null ][, string $valueFormat = '%s' ][, bool $includeSelf = false ][, int $until = null ]) : array<string|int, mixed>
Parameters
$column : string

The column name for the wp_realmedialibrary SQL table. "slug", "name", "absolutePath", ... This string is not escaped when you pass it through this function

$value : mixed = null

The value the column should have

$valueFormat : string = '%s'

The value format for $value ($wpdb->prepare) This string is not escaped when you pass it through this function

$includeSelf : bool = false

Set true to add self to list

$until : int = null

The highest allowed folder id. If null _wp_rml_root() is used

Tags
since
3.3
Return values
array<string|int, mixed>

folderId => columnValue, first id is the first found parent

anyParentHasMetadata()

Get all parents which meets a given meta key value or meta key value is not empty.

public anyParentHasMetadata(string $meta_key[, mixed $meta_value = null ][, string $valueFormat = '%s' ][, bool $includeSelf = false ][, int $until = null ]) : array<string|int, mixed>
Parameters
$meta_key : string

The meta key name for the wp_realmedialibrary_meta SQL table. This string is not escaped when you pass it through this function

$meta_value : mixed = null

The value the meta key should have

$valueFormat : string = '%s'

The value format for $value ($wpdb->prepare) This string is not escaped when you pass it through this function

$includeSelf : bool = false

Set true to add self to list

$until : int = null

The highest allowed folder id. If null _wp_rml_root() is used

Tags
since
3.3
Return values
array<string|int, mixed>

Array with keys: id (meta_id), folderId, value (meta_value), first id is the first found parent

contentIndex()

(Pro only) Index the order table.

public contentIndex([bool $delete = true ]) : bool
Parameters
$delete : bool = true

Delete the old order

Tags
throws
OnlyInProVersionException
Return values
bool

contentOrder()

(Pro only) See API function for more information.

public contentOrder(int $attachmentId, int|false $nextId[, int|bool $lastIdInView = false ]) : true
Parameters
$attachmentId : int
$nextId : int|false
$lastIdInView : int|bool = false
Tags
throws
Exception
throws
OnlyInProVersionException
see
wp_attachment_order_update()
Return values
true

contentOrderBy()

(Pro only) Start to order the given folder content by a given order type.

public contentOrderBy(string $orderby[, bool $writeMetadata = true ]) : bool
Parameters
$orderby : string

The order type key

$writeMetadata : bool = true
Tags
throws
OnlyInProVersionException
Return values
bool

contentReindex()

(Pro only) This function retrieves the order of the order table and removes empty spaces, for example: <pre>0 1 5 7 8 9 10 => 0 1 2 3 4 5 6</pre>

public contentReindex() : bool
Tags
throws
OnlyInProVersionException
Return values
bool

contentRestoreOldCustomNr()

(Pro only) Restore the current order number to the old custom order number.

public contentRestoreOldCustomNr() : bool
Tags
throws
OnlyInProVersionException
Return values
bool

forceContentCustomOrder()

Override this functionality to force the content custom order in the posts_clauses.

public forceContentCustomOrder() : bool
Tags
since
4.0.2
Return values
bool

getAbsolutePath()

Creates a absolute path. If the absolute path is empty or forced to, it will be updated in the database, too.

public getAbsolutePath([bool $force = false ][, bool $fromSetName = false ]) : string
Parameters
$force : bool = false

Forces to regenerate the absolute path

$fromSetName : bool = false

For internal usage only

Return values
string

getAllowedChildrenTypes()

Get all allowed children folder types.

public getAllowedChildrenTypes() : bool|array<string|int, int>
Return values
bool|array<string|int, int>

Array with allowed types or TRUE for all types allowed

getAllParents()

Get all parents of this folder.

public getAllParents([int $until = null ][, int $colIdx = 0 ]) : array<string|int, int>
Parameters
$until : int = null

The highest allowed folder id. If null _wp_rml_root() is used

$colIdx : int = 0

The index returning for the wp_rml_create_all_parents_sql() query

Tags
since
3.3
Return values
array<string|int, int>

Folder ids, first id is the first parent

getAttachmentNextTo()

(Pro only) Get the next attachment row for a specific attachment. It returns false if the attachment is at the end or the folder has no custom content order.

public getAttachmentNextTo(int $attachmentId) : array<string|int, mixed>
Parameters
$attachmentId : int

The attachment id

Tags
since
4.0.8

Now the method returns an array instead of int

throws
OnlyInProVersionException
Return values
array<string|int, mixed>

or null

getCnt()

Gets the count of the files in this folder.

public getCnt([bool $forceReload = false ]) : int
Parameters
$forceReload : bool = false

If true the count cache gets reloaded

Tags
since
3.3.1
Return values
int

getContentAggregationNr()

(Pro only) Gets the biggest order number;

public getContentAggregationNr([string $function = 'MAX' ]) : int
Parameters
$function : string = 'MAX'

The SQL aggregation function (MIN or MAX)

Tags
throws
OnlyInProVersionException
Return values
int

getContentNrOf()

(Pro only) Get the order number for a specific attachment in this folder.

public getContentNrOf(int $attachmentId) : int|bool
Parameters
$attachmentId : int

The attachment id

Tags
throws
OnlyInProVersionException
Return values
int|bool

getContentOldCustomNrCount()

(Pro only) Get the old custom order number count so we can decide if already available.

public getContentOldCustomNrCount() : int
Tags
throws
OnlyInProVersionException
Return values
int

getId()

Get the folder id.

public getId() : int
Return values
int

getMaxOrder()

Get the maximal order number of the children.

public getMaxOrder() : int
Tags
since
3.3.1
Return values
int

Max order number

getName()

Get the folder name.

public getName([bool $htmlentities = false ]) : string
Parameters
$htmlentities : bool = false

If true the name is returned htmlentitied for output

Return values
string

getOrder()

Get the order number.

public getOrder() : int
Tags
since
3.3.1
Return values
int

getOwner()

Get the creator/owner of the folder.

public getOwner() : int
Tags
since
3.3
Return values
int

ID of the user

getParent()

Get the parent folder id.

public getParent() : int
Return values
int

getPath()

Creates a absolute path without slugging' the names.

public getPath([string $implode = '/' ][, callable $map = 'htmlentities' ][, callable $filter = null ]) : string
// Get valid physical folder name
$folder->getPath("/", "_wp_rml_sanitize_filename");
Parameters
$implode : string = '/'

Delimiter for the folder names

$map : callable = 'htmlentities'

Map the names with this function. Pass null to skip this map function

$filter : callable = null

Filter folders

Return values
string

htmlentitied path

getPlain()

Gets a plain array with folder properties.

public getPlain([bool $deep = false ]) : array<string|int, mixed>
Parameters
$deep : bool = false

Return the children as plain object array

Return values
array<string|int, mixed>

or null when not visible

getRestrictions()

Get the restrictions of this folder.

public getRestrictions() : array<string|int, string>
Return values
array<string|int, string>

getRestrictionsCount()

Get the count of the restrictions.

public getRestrictionsCount() : int
Return values
int

getRowData()

Get the full row of the SQL query.

public getRowData([string $field = null ]) : mixed
Parameters
$field : string = null

The field name

Tags
since
3.3
Return values
mixed

Any object or false

getSlug()

Returns a sanitized title for the folder. If the slug is empty or forced to, it will be updated in the database, too.

public getSlug([bool $force = false ][, bool $fromSetName = false ]) : string
Parameters
$force : bool = false

Forces to regenerate the slug

$fromSetName : bool = false

For internal usage only

Return values
string

getType()

Return the type for the given folder. For example: 0 = Folder, 1 = Collection, 2 = Gallery

public getType() : int
Return values
int

getTypeDescription()

Get the type description for this folder.

public getTypeDescription([string $default = null ]) : string
Parameters
$default : string = null

The default (if null folder description is used as default)

Tags
since
3.3.1
see
Filter

RML/Folder/Type/Description

Return values
string

getTypeName()

Get the type name for this folder. For example: Folder, Collection, Gallery, Unorganized.

public getTypeName([string $default = null ]) : string
Parameters
$default : string = null

The default (if null "Folder" is used as default)

Tags
since
3.3.1
see
Filter

RML/Folder/Type/Name

Return values
string

hasChildren()

Checks if this folder has a children with a given name.

public hasChildren(string $name[, bool $returnObject = false ]) : bool
Parameters
$name : string

Name of folder

$returnObject : bool = false

If set to true and a children with this name is found, then return the object for this folder

Tags
since
3.3

Now it checks for a given folder name instead the slug

Return values
bool

insert()

Insert an amount of post ID's (attachments) to this folder.

public insert(array<string|int, int> $ids[, bool $supress_validation = false ][, bool $isShortcut = false ]) : true
Parameters
$ids : array<string|int, int>

Array of post ids

$supress_validation : bool = false

Suppress the permission validation

$isShortcut : bool = false

Determines, if the post's should be "copied" to the folder (no physical copy)

Tags
throws
Exception
see
wp_rml_move()
see
wp_rml_create_shortcuts()
Return values
true

is()

Check if the folder object is a given type.

public is(int $folder_type) : bool
Parameters
$folder_type : int

The folder type

Return values
bool

isContentCustomOrderAllowed()

Checks if the folder is allowed to use custom content order.

public isContentCustomOrderAllowed() : bool
Return values
bool

isRestrictFor()

Checks if this folder has a special restriction.

public isRestrictFor(string $restriction) : bool
Parameters
$restriction : string

The restriction to check

Tags
see
IFolder::setRestrictions()
Return values
bool

isValidChildrenType()

Checks if a given folder type is allowed in this folder.

public isValidChildrenType(int $type) : bool
Parameters
$type : int

The type

Tags
see
IFolder::getAllowedChildrenTypes()
since
4.12.1

This function returns always true in Lite version

Return values
bool

isVisible()

Check if the folder object is visible to the user.

public isVisible() : bool
Return values
bool

orderSubfolders()

(Pro only) Start to order the given folder subfolders by a given order type.

public orderSubfolders(string $orderby[, bool $writeMetadata = true ]) : bool
Parameters
$orderby : string

The order type key

$writeMetadata : bool = true
Tags
throws
OnlyInProVersionException
since
4.4
Return values
bool

postsClauses()

Override the default posts_clauses join and orderby instead of the RML standard.

public postsClauses(array<string|int, mixed> $pieces) : bool

This can be useful if you want to take the order from another relationship. You have to return true if you have overwritten it.

Parameters
$pieces : array<string|int, mixed>

The posts_clauses $pieces parameter

Tags
since
4.0.2
Return values
bool

read()

Fetch all attachment ids currently in this folder. It uses the default WP_Query to fetch the ids. You can also use the WP_Query like: ```php $query = new \WP_Query([ 'post_status' => 'inherit', 'post_type' => 'attachment', 'rml_folder' => 4, // Can also be an array of integers 'rml_include_children' => false // (optional) Include files of subfolder, you have to use wp_rml_all_children_sql_supported(false, 'function') for checking support ]); ```

public read([string $order = null ][, string $orderby = null ]) : array<string|int, int>
Parameters
$order : string = null

The order "ASC" or "DESC"

$orderby : string = null

Use "rml" to get ids ordered by custom order

Return values
array<string|int, int>

Post ids

reindexChildrens()

(Pro only) Reindex the children folders so the "ord" number is set right.

public reindexChildrens([bool $resetData = false ]) : bool
Parameters
$resetData : bool = false

If true, the structure is reset

Tags
since
4.12.1

This function is only available in PRO-Version.

since
4.12.1

This function is only available in PRO-Version

Return values
bool

relocate()

Relocate a folder to a given place in the folder structure.

public relocate(int $parentId[, int $nextFolderId = false ]) : bool|array<string|int, string>
Parameters
$parentId : int

The parent id

$nextFolderId : int = false

The next folder id it should be prepend or false for the end

Tags
throws
Exception
since
4.12.1

This function ignores the $parentId parameter in Lite version as creating subfolders is no longer supported

Return values
bool|array<string|int, string>

true or array with errors

setName()

Renames a folder and then checks, if there is no duplicate folder in the parent folder.

public setName(string $name[, bool $supress_validation = false ]) : bool
Parameters
$name : string

String New name of the folder

$supress_validation : bool = false

Suppress the permission validation

Tags
throws
Exception
Return values
bool

setParent()

Changes the parent folder of this folder.

public setParent(int $id[, int $ord = -1 ][, bool $force = false ]) : bool
Parameters
$id : int

The new parent (use -1 for root)

$ord : int = -1

The order number

$force : bool = false

If true no permission checks are executed

Tags
throws
Exception
since
4.12.1

This function ignores the $id parameter in Lite version as creating subfolders is no longer supported

Return values
bool

setRestrictions()

Set restrictions for this folder. Allowed restrictions for folders:

public setRestrictions([array<string|int, string> $restrictions = [] ]) : bool
  • par Restrict to change the parent id
  • rea Restrict to rearrange the hierarchical levels of all subfolders (it is downwards all subfolders!) and cannot be inherited
  • cre Restrict to create new subfolders
  • ins Restrict to insert/upload new attachments, automatically moved to root if upload
  • ren Restrict to rename the folder
  • del Restrict to delete the folder
  • mov Restrict to move files outside the folder

You can append a ">" after each permission so it is inherited in each created subfolder: "cre>", "ins>", ...

Parameters
$restrictions : array<string|int, string> = []

Array with restrictions

Return values
bool

setVisible()

Sets the folders visibility to the user.

public setVisible(bool $visible) : mixed
Parameters
$visible : bool

updateThisAndChildrensAbsolutePath()

Iterate all children of this folder recursively and update the absolute path. Use this function with caution because it can be time intensive.

public updateThisAndChildrensAbsolutePath() : mixed

        
On this page

Search results