Documentation

folders.php

Table of Contents

Functions

wp_rml_debug()  : mixed
This function is recommend for RML add-ons. You can use this function to generate log entries in the database when Settings > Media > Debug is enabled.
is_rml_folder()  : bool
Checks, if a given variable is an implementation of the IFolder interface.
wp_rml_get_parent_id()  : int
Get the parent ID of a given folder id.
wp_rml_objects()  : array<string|int, IFolder>
Get all available folders, collections, galleries, .
wp_rml_root_childs()  : array<string|int, IFolder>
Gets the first level childs of the media library.
wp_rml_create()  : int|array<string|int, string>
Creates a folder. At first it checks if a folder in parent already exists.
wp_rml_create_p()  : int|array<string|int, string>
(Pro only) Creates multiple folders like "test/test2". At first it checks if a folder in parent already exists.
wp_rml_create_or_return_existing_id()  : int|array<string|int, string>
Wrapper function for wp_rml_create.
wp_rml_rename()  : bool|array<string|int, string>
Renames a folder and then checks, if there is no duplicate folder in the parent folder.
wp_rml_delete()  : bool|array<string|int, string>
Deletes a folder by ID.
wp_rml_update_count()  : string|null
Handle the count cache for the folders. This should avoid a lack SQL subquery which loads data from the postmeta table.
wp_rml_selector()  : string
This function returns a HTML code (input[type="hidden"]) which gets nicely rendered via Javascript (FolderSelector). If you need a more complex implementation have a look at FolderSelector.js module.
wp_rml_dropdown()  : string
This functions returns a HTML formatted string which contains options-tag elements with all folders, collections and galleries.
wp_rml_dropdown_collection()  : string
This functions returns a HTML formatted string which contains `<options>` elements with all folders, collections and galleries.
wp_rml_dropdown_gallery()  : string
This functions returns a HTML formatted string which contains option-tag elements with all folders, collections and galleries.
wp_rml_dropdown_gallery_or_collection()  : string
This functions returns a HTML formatted string which contains option-tag elements with all folders, collections and galleries.
wp_rml_is_type()  : bool
Determines if a Folder is a special folder type.
wp_rml_get_object_by_id()  : IFolder
A shortcut function for the wp_rml_get_by_id function that ensures, that a IFolder object is returned. For -1 the root instance is returned.
wp_rml_get_by_id()  : IFolder
This functions checks if a specific folder exists by ID and is a given allowed RML Folder Type. If the given folder is _wp_rml_root you will get the first level folders.
wp_rml_get_by_absolute_path()  : IFolder
This functions checks if a specific folder exists by absolute path and is a given allowed RML Folder Type.
wp_rml_register_creatable()  : mixed
Register a new folder type for RML. It does not check if the creatable type is already registered.
_wp_rml_root()  : int
Get the parent root folder for a given blog id.
wp_rml_active()  : bool
Checks if RML is active for the current user.
_wp_rml_sanitize()  : string
Sanitize to a valid slug name for a given folder name. If the passed folder name contains only invalid characters, then it falls back to the base64 encode.
_wp_rml_sanitize_filename()  : mixed
wp_rml_structure_reset()  : IFolder
Resets the structure. This function must be called when you create a new folder for example and to register it to the structure.
wp_rml_structure()  : IStructure
Get the main working structure.
wp_rml_create_all_parents_sql()  : string|bool
Returns a SQL query to get all parents for a folder id.
wp_rml_all_children_sql_supported()  : bool
Checks if the wp_rml_create_all_children_sql() SQL is supported by the current used database system. The function itself creates a dummy table and performs the SQL and checks if the result is as expected. The "support" result is cached site-wide.
wp_rml_create_all_children_sql()  : string|bool
Returns a SQL query to get all children for a folder id.
wp_rml_last_queried_folder()  : int
Set or get the last queried folder.

Functions

wp_rml_debug()

This function is recommend for RML add-ons. You can use this function to generate log entries in the database when Settings > Media > Debug is enabled.

wp_rml_debug(mixed|string $message[, string $methodOrFunction = null ]) : mixed
Parameters
$message : mixed|string

The message

$methodOrFunction : string = null

METHOD or FUNCTION

Tags
since
4.0.2

is_rml_folder()

Checks, if a given variable is an implementation of the IFolder interface.

is_rml_folder(int|IFolder $obj) : bool
Parameters
$obj : int|IFolder

Object or int (ID)

Return values
bool

wp_rml_get_parent_id()

Get the parent ID of a given folder id.

wp_rml_get_parent_id(int $id) : int
Parameters
$id : int

The id of the folder, collection, ...

Return values
int —

or null

wp_rml_objects()

Get all available folders, collections, galleries, .

wp_rml_objects() : array<string|int, IFolder>

..

Return values
array<string|int, IFolder>

wp_rml_root_childs()

Gets the first level childs of the media library.

wp_rml_root_childs() : array<string|int, IFolder>
Return values
array<string|int, IFolder>

wp_rml_create()

Creates a folder. At first it checks if a folder in parent already exists.

wp_rml_create(string $name, int $parent, int $type[, array<string|int, string> $restrictions = [] ][, bool $supress_validation = false ][, bool $return_existing_id = false ]) : int|array<string|int, string>

Then it checks if the given type is allowed in the parent.

It is highly recommend, to use wp_rml_structure_reset after you created your folders.

Parameters
$name : string

String Name of the folder

$parent : int

int ID of the parent (_wp_rml_root() for root)

$type : int

integer 0|1|2, Folder.inc

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

Restrictions for this folder

$supress_validation : bool = false

Supress the permission validation

$return_existing_id : bool = false

If true and the folder already exists, then return the ID of the existing folder

Tags
throws
OnlyInProVersionException
since
4.12.1

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

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

int (ID) when successfully array with error strings

wp_rml_create_p()

(Pro only) Creates multiple folders like "test/test2". At first it checks if a folder in parent already exists.

wp_rml_create_p(string $name, int $parent, int $type[, array<string|int, string> $restrictions = [] ][, bool $supress_validation = false ]) : int|array<string|int, string>

Then it checks if the given type is allowed in the parent.

It is highly recommend, to use wp_rml_structure_reset after you created your folders.

Parameters
$name : string

String Name of the folder

$parent : int

int ID of the parent (_wp_rml_root() for root)

$type : int

integer 0|1|2, Folder.inc

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

Restrictions for this folder, it is only applied to first folder

$supress_validation : bool = false

Supress the permission validation

Tags
throws
OnlyInProVersionException
since
4.12.0
since
4.12.1

This function is no longer available in PRO version

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

int (ID) when successfully array with error strings

wp_rml_create_or_return_existing_id()

Wrapper function for wp_rml_create.

wp_rml_create_or_return_existing_id(string $name, int $parent, int $type[, array<string|int, string> $restrictions = [] ][, bool $supress_validation = false ]) : int|array<string|int, string>
Parameters
$name : string

String Name of the folder

$parent : int

int ID of the parent (_wp_rml_root() for root)

$type : int

integer 0|1|2, Folder.inc

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

Restrictions for this folder

$supress_validation : bool = false

Supress the permission validation

Tags
since
4.12.1

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

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

int (ID) when successfully array with error strings

wp_rml_rename()

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

wp_rml_rename(string $name, int $id[, bool $supress_validation = false ]) : bool|array<string|int, string>
Parameters
$name : string

String New name of the folder

$id : int

The ID of the folder

$supress_validation : bool = false

Suppress the permission validation

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

true or array with error strings

wp_rml_delete()

Deletes a folder by ID.

wp_rml_delete(int $id[, bool $supress_validation = false ]) : bool|array<string|int, string>
Parameters
$id : int

The ID of the folder

$supress_validation : bool = false

Supress the permission validation

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

True or array with error string

wp_rml_update_count()

Handle the count cache for the folders. This should avoid a lack SQL subquery which loads data from the postmeta table.

wp_rml_update_count([array<string|int, int> $folders = null ][, array<string|int, int> $attachments = null ][, bool $onlyReturn = false ]) : string|null
Parameters
$folders : array<string|int, int> = null

Array of folders ID, if null then all folders with cnt NULL are updated

$attachments : array<string|int, int> = null

Array of attachments ID, is merged with $folders if given

$onlyReturn : bool = false

Set to true if you only want the SQL query

Return values
string|null

wp_rml_selector()

This function returns a HTML code (input[type="hidden"]) which gets nicely rendered via Javascript (FolderSelector). If you need a more complex implementation have a look at FolderSelector.js module.

wp_rml_selector([array<string|int, mixed> $options = [] ]) : string

$options:

  • mixed selected=Root The selected item, "" => "None", _wp_rml_root() => "Root", int => Folder ID
  • int[] disabled Which folder types are disabled
  • boolean nullable=false Defines if null ('') is allowed as value
  • boolean editable=true Define if the selector is editable
  • string name Name for the input
  • string title Title in the modal dialog
Parameters
$options : array<string|int, mixed> = []
Tags
since
4.3
Return values
string

wp_rml_dropdown()

This functions returns a HTML formatted string which contains options-tag elements with all folders, collections and galleries.

wp_rml_dropdown(mixed $selected, array<string|int, int> $disabled[, bool $useAll = true ]) : string

This function should only be used if you want to provide

Parameters
$selected : mixed

The selected item, "" => "All Files", _wp_rml_root() => "Root", int => Folder ID. Can also be an array for multiple select (since 3.1.2)

$disabled : array<string|int, int>

Which folder types are disabled. Default disabled is RML_TYPE_COLLECTION

$useAll : bool = true

boolean Defines, if "All Files" should be showed

Return values
string

wp_rml_dropdown_collection()

This functions returns a HTML formatted string which contains `<options>` elements with all folders, collections and galleries.

wp_rml_dropdown_collection(mixed $selected) : string

Note: Only COLLECTIONS are SELECTABLE!

This function should only be used if you want to provide

Parameters
$selected : mixed

The selected item, "" => "All Files", _wp_rml_root() => "Root", int => Folder ID. Can also be an array for multiple select (since 3.1.2)

Return values
string

wp_rml_dropdown_gallery()

This functions returns a HTML formatted string which contains option-tag elements with all folders, collections and galleries.

wp_rml_dropdown_gallery(mixed $selected) : string

Note: Only GALLERIES are SELECTABLE!

This function should only be used if you want to provide

Parameters
$selected : mixed

The selected item, "" => "All Files", _wp_rml_root() => "Root", int => Folder ID. Can also be an array for multiple select (since 3.1.2)

Return values
string

wp_rml_dropdown_gallery_or_collection()

This functions returns a HTML formatted string which contains option-tag elements with all folders, collections and galleries.

wp_rml_dropdown_gallery_or_collection(mixed $selected) : string

Note: Only GALLERIES AND COLLECTIONS are SELECTABLE!

Parameters
$selected : mixed

The selected item, "" => "All Files", _wp_rml_root() => "Root", int => Folder ID. Can also be an array for multiple select (since 3.1.2)

Return values
string

wp_rml_is_type()

Determines if a Folder is a special folder type.

wp_rml_is_type(IFolder|int $folder, array<string|int, int> $allowed) : bool
Parameters
$folder : IFolder|int

The folder object

$allowed : array<string|int, int>

Which folder types are allowed

Return values
bool

wp_rml_get_object_by_id()

A shortcut function for the wp_rml_get_by_id function that ensures, that a IFolder object is returned. For -1 the root instance is returned.

wp_rml_get_object_by_id(int $id[, array<string|int, int> $allowed = null ]) : IFolder
Parameters
$id : int
$allowed : array<string|int, int> = null
Return values
IFolder

wp_rml_get_by_id()

This functions checks if a specific folder exists by ID and is a given allowed RML Folder Type. If the given folder is _wp_rml_root you will get the first level folders.

wp_rml_get_by_id(int $id[, array<string|int, int> $allowed = null ][, bool $mustBeFolderObject = false ][, bool $nullForRoot = true ]) : IFolder
Parameters
$id : int

Folder ID

$allowed : array<string|int, int> = null

Which folder types are allowed. If null all folder types are allowed.

$mustBeFolderObject : bool = false

Defines if the function may return the wp_rml_root_childs result

$nullForRoot : bool = true

If set to false and $id == -1 then the Root instance is returned

Return values
IFolder

wp_rml_get_by_absolute_path()

This functions checks if a specific folder exists by absolute path and is a given allowed RML Folder Type.

wp_rml_get_by_absolute_path(string $path[, array<string|int, int> $allowed = null ]) : IFolder
Parameters
$path : string

Folder Absolute Path

$allowed : array<string|int, int> = null

Which folder types are allowed. If null all folder types are allowed.

Return values
IFolder

wp_rml_register_creatable()

Register a new folder type for RML. It does not check if the creatable type is already registered.

wp_rml_register_creatable(string $qualified, int $type[, bool $onRegister = false ]) : mixed
Parameters
$qualified : string

The qualified name of the class representing the creatable

$type : int

The type of the creatable. It must be the same as in yourClass::getType is returned

$onRegister : bool = false

Calls the yourClass::onRegister function

_wp_rml_root()

Get the parent root folder for a given blog id.

_wp_rml_root() : int
Return values
int —

Folder id

wp_rml_active()

Checks if RML is active for the current user.

wp_rml_active() : bool
Tags
since
4.0.2
Return values
bool

_wp_rml_sanitize()

Sanitize to a valid slug name for a given folder name. If the passed folder name contains only invalid characters, then it falls back to the base64 encode.

_wp_rml_sanitize(string $name[, bool $database = false ][, int $exclude = -1 ]) : string
Parameters
$name : string

The name of the folder

$database : bool = false

If true the name is generated unique from the database slugs

$exclude : int = -1
Return values
string

_wp_rml_sanitize_filename()

_wp_rml_sanitize_filename(mixed $name) : mixed
Parameters
$name : mixed

wp_rml_structure_reset()

Resets the structure. This function must be called when you create a new folder for example and to register it to the structure.

wp_rml_structure_reset([int $root = null ][, bool $fetchData = true ][, int $returnId = false ]) : IFolder

ATTENTION: This function will be declared as deprecated soon, because it is planned to automatically reset the structure data / reset folder data (lazy loading of Folder objects).

Parameters
$root : int = null

The root folder to read the structure

$fetchData : bool = true

Determine if the data should be re-fetched

$returnId : int = false

If set this folder is returned

Return values
IFolder —

If $returnId is set

wp_rml_structure()

Get the main working structure.

wp_rml_structure() : IStructure
Tags
since
3.3.1
Return values
IStructure

wp_rml_create_all_parents_sql()

Returns a SQL query to get all parents for a folder id.

wp_rml_create_all_parents_sql(IFolder|int $folder[, bool $includeSelf = false ][, int $until = null ][, array<string|int, mixed> $options = null ]) : string|bool

The first result for this SQL statement is the first parent and so on... Use rmltmp.lvl field for the depth number upwards. To avoid performance lacks you should figure out if there is already an action available to search for a meta_key in the action RML/$action/AnyParentHasMeta.

$options parameters:

"fields"    => (string) SELECT fields (default: "rmldata.*, rmltmp.lvl AS lvlup")
"join"      => (string) JOIN statement (default: "")
"where"     => (string) Replace WHERE statement, it is preferred to use afterWhere (default: "rmltmp.lvl > " . ($includeSelf === true ? "-1" : "0"))
"afterWhere"=> (string) Additional WHERE statement to the above WHERE (default: "")
"orderby"   => (string) ORDER BY statement (default: "rmltmp.lvl ASC")
"limit"     => (string) LIMIT statement (default: "")

Note: The created SQL is supported by all well-known MySQL systems.

Parameters
$folder : IFolder|int

The folder object or folder id

$includeSelf : bool = false

Set true to include self (passed $folder)

$until : int = null

Until this folder id

$options : array<string|int, mixed> = null

Additional options for the SQL query, see above

Return values
string|bool —

SQL query or false if something went wrong

wp_rml_all_children_sql_supported()

Checks if the wp_rml_create_all_children_sql() SQL is supported by the current used database system. The function itself creates a dummy table and performs the SQL and checks if the result is as expected. The "support" result is cached site-wide.

wp_rml_all_children_sql_supported([bool $force = false ][, string $type = 'legacy' ]) : bool
Parameters
$force : bool = false

If true the database check is performed again

$type : string = 'legacy'

The type which is minimum required. Possible values: 'function' (MySQL UDF) or 'legacy' (default, old variant)

Tags
since
4.0.9
Return values
bool

wp_rml_create_all_children_sql()

Returns a SQL query to get all children for a folder id.

wp_rml_create_all_children_sql(IFolder|int $folder[, bool $includeSelf = false ][, array<string|int, mixed> $options = null ]) : string|bool

The first result for this SQL statement is the first children and so on...

$options parameters:

"fields"       => (string) SELECT fields (default: "rmldata.*"),
"join"         => (string) JOIN statement (default: ""),
"where"        => (string) Replace WHERE statement, it is preferred to use afterWhere (default: '1=1 ' . ($includeSelf === true ? "" : $wpdb->prepare(" AND rmldata.id != %d", $folderId))),
"afterWhere"   => (string) Additional WHERE statement to the above WHERE (default: ""),
"orderby"      => (string) ORDER BY statement (default: "rmldata.parent, rmldata.ord"),
"limit"        => (string) LIMIT statement (default: "")

Note: Not all database systems do support this kind of SQL query. You have to use the wp_rml_all_children_sql_supported() API function to check if it is supported.

Parameters
$folder : IFolder|int

The folder object or folder id

$includeSelf : bool = false

Set true to include self (passed $folder)

$options : array<string|int, mixed> = null

Additional options for the SQL query, see above

Return values
string|bool —

SQL query or false if something went wrong

wp_rml_last_queried_folder()

Set or get the last queried folder.

wp_rml_last_queried_folder([int $folder = null ]) : int
Parameters
$folder : int = null

The folder id (0 is handled as "All files" folder)

Tags
since
4.0.5
Return values
int 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results