Since: 6.0.0 Initial implementation

class Documents extends DolibarrApi (View source)

API class for receive files

Properties

protected DoliDB $db from  DolibarrApi
Restler $r from  DolibarrApi

Methods

__construct()

Constructor

string|array<string, mixed>
_checkValForAPI(string $field, string|string[] $value, object $object)

Check and convert a string depending on its type/name.

object
_filterObjectProperties(object $object, string $properties)

Filter properties that will be returned on object

object
_cleanObjectDatas(object $object)

Clean sensitive object data

static bool
_checkAccessToResource(string $resource, int $resource_id = 0, string $dbtablename = '', string $feature2 = '', string $dbt_keyfield = 'fk_soc', string $dbt_select = 'rowid')

Check access by user to a given resource

bool|string
_checkFilters(string $sqlfilters, string $error = '')

Return if a $sqlfilters parameter is valid Function no more used. Kept for backward compatibility with old APIs of modules

static string
_forge_criteria_callback(string[] $matches)

Function to forge a SQL criteria from a Generic filter string.

array
index(string $modulepart, string $original_file = '')

Download a document

array
builddoc(string $modulepart, string $original_file = '', string $doctemplate = '', string $langcode = '')

Build a document

array
getDocumentsListByElement(string $modulepart, int $id = 0, string $ref = '', string $sortfield = '', string $sortorder = '', int $limit = 100, int $page = 0, string $content_type = '', bool $pagination_data = false)

List documents of an element

string
post(string $filename, string $modulepart, string $ref = '', string $subdir = '', string $filecontent = '', string $fileencoding = '', int $overwriteifexists = 0, int $createdirifnotexists = 1, int $position = 0, string $cover = '', array $array_options = [], int $generateThumbs = 0)

Upload a document

array
delete(string $modulepart, string $original_file)

Delete a document

Details

__construct()

Constructor

protected string|array<string, mixed> _checkValForAPI(string $field, string|string[] $value, object $object)

Check and convert a string depending on its type/name.

Parameters

string $field

Field name

string|string[] $value

Value to check/clean

object $object Object

Return Value

string|array<string, mixed>

Value cleaned

protected object _filterObjectProperties(object $object, string $properties)

Filter properties that will be returned on object

Parameters

object $object

Object to clean

string $properties

Comma separated list of properties names

Return Value

object

Object with cleaned properties

protected object _cleanObjectDatas(object $object)

Clean sensitive object data

Parameters

object $object

Object to clean

Return Value

object

Object with cleaned properties

static protected bool _checkAccessToResource(string $resource, int $resource_id = 0, string $dbtablename = '', string $feature2 = '', string $dbt_keyfield = 'fk_soc', string $dbt_select = 'rowid')

Check access by user to a given resource

Parameters

string $resource

element to check

int $resource_id

Object ID if we want to check a particular record (optional) is linked to a owned thirdparty (optional).

string $dbtablename

'TableName&SharedElement' with Tablename is table where object is stored. SharedElement is an optional key to define where to check entity. Not used if objectid is null (optional)

string $feature2

Feature to check, second level of permission (optional). Can be or check with 'level1|level2'.

string $dbt_keyfield

Field name for socid foreign key if not fk_soc. Not used if objectid is null (optional)

string $dbt_select

Field name for select if not rowid. Not used if objectid is null (optional)

Return Value

bool

protected bool|string _checkFilters(string $sqlfilters, string $error = '')

Return if a $sqlfilters parameter is valid Function no more used. Kept for backward compatibility with old APIs of modules

Parameters

string $sqlfilters

sqlfilter string

string $error

Error message

Return Value

bool|string

True if valid, False if not valid

static protected string _forge_criteria_callback(string[] $matches)

Function to forge a SQL criteria from a Generic filter string.

Function no more used. Kept for backward compatibility with old APIs of modules

Parameters

string[] $matches

Array of found string by regex search. Each entry is 1 and only 1 criteria. Example: "t.ref:like:'SO-%'", "t.date_creation:<:'20160101'", "t.date_creation:<:'2016-01-01 12:30:00'", "t.nature:is:NULL", "t.field2:isnot:NULL"

Return Value

string

Forged criteria. Example: "t.field like 'abc%'"

array index(string $modulepart, string $original_file = '')

Since: 7.0.0 Initial implementation

Download a document

Note that, this API is similar to using the wrapper link "documents.php" to download a file (used for internal HTML links of documents into application), but with no need to have a session cookie (the token is used instead).

Parameters

string $modulepart

Name of module or area concerned by file download ('facture', ...)

string $original_file

Relative path with filename, relative to modulepart (for example: IN201701-999/IN201701-999.pdf)

Return Value

array

List of documents

Exceptions

RestException
RestException
RestException

array builddoc(string $modulepart, string $original_file = '', string $doctemplate = '', string $langcode = '')

Since: 7.0.0 Initial implementation, support for invoice, order and proposal documents

Build a document

Test sample 1: { "modulepart": "invoice", "original_file": "FA1701-001/FA1701-001.pdf", "doctemplate": "crabe", "langcode": "fr_FR" }.

Supported modules: invoice, order, proposal, contract, supplier invoice, shipment, mrp

Parameters

string $modulepart

Name of module or area concerned by file download ('thirdparty', 'member', 'proposal', 'supplier_proposal', 'order', 'supplier_order', 'invoice', 'supplier_invoice', 'shipment', 'project', ...)

string $original_file

Relative path with filename, relative to modulepart (for example: IN201701-999/IN201701-999.pdf).

string $doctemplate

Set here the doc template to use for document generation (If not set, use the default template).

string $langcode

Language code like 'en_US', 'fr_FR', 'es_ES', ... (If not set, use the default language).

Return Value

array

List of documents

Exceptions

RestException
RestException
RestException
RestException
RestException

array getDocumentsListByElement(string $modulepart, int $id = 0, string $ref = '', string $sortfield = '', string $sortorder = '', int $limit = 100, int $page = 0, string $content_type = '', bool $pagination_data = false)

Since: 7.0.0 Initial implementation

List documents of an element

Use element ID or Ref. Supported modules: thirdparty, user, member, proposal, order, supplier_order, shipment, invoice, supplier_invoice, product, event, expensereport, knowledgemanagement, category, contract, project, project_task

Parameters

string $modulepart

Name of module or area concerned ('thirdparty', 'member', 'proposal', 'order', 'invoice', 'supplier_invoice', 'shipment', 'project', 'project_task', ...)

int $id

ID of element

string $ref

Ref of element

string $sortfield

Sort criteria ('','fullname','relativename','name','date','size')

string $sortorder

Sort order ('asc' or 'desc')

int $limit

List limit

int $page

Page number

string $content_type

Filter on content-type (example 'application/pdf' or 'application/pdf,image/jpeg'))

bool $pagination_data

If this parameter is set to true the response will include pagination data. Default value is false. Page starts from 0*

Return Value

array

Array of documents with path

Exceptions

RestException
RestException
RestException
RestException
RestException

string post(string $filename, string $modulepart, string $ref = '', string $subdir = '', string $filecontent = '', string $fileencoding = '', int $overwriteifexists = 0, int $createdirifnotexists = 1, int $position = 0, string $cover = '', array $array_options = [], int $generateThumbs = 0)

Since: 6.0.0 Initial implementation

Upload a document

Test sample for invoice: { "filename": "mynewfile.txt", "modulepart": "invoice", "ref": "FA1701-001", "subdir": "", "filecontent": "content text", "fileencoding": "", "overwriteifexists": "0" }. Test sample for supplier invoice: { "filename": "mynewfile.txt", "modulepart": "supplier_invoice", "ref": "FA1701-001", "subdir": "", "filecontent": "content text", "fileencoding": "", "overwriteifexists": "0" }. Test sample for medias file: { "filename": "mynewfile.txt", "modulepart": "medias", "ref": "", "subdir": "image/mywebsite", "filecontent": "Y29udGVudCB0ZXh0Cg==", "fileencoding": "base64", "overwriteifexists": "0" }.

Supported modules: invoice, order, supplier_order, task/project_task, product/service, expensereport, fichinter, member, propale, agenda, contact

Parameters

string $filename

Name of file to create ('FA1705-0123.txt')

string $modulepart

Name of module or area concerned by file upload ('product', 'service', 'invoice', 'proposal', 'project', 'project_task', 'supplier_invoice', 'expensereport', 'member', ...)

string $ref

Reference of object (This will define subdir automatically and store submitted file into it). For third party use object ID not name.

string $subdir

Subdirectory (Only if $ref is not provided)

string $filecontent

File content (string with file content. An empty file will be created if this parameter is not provided)

string $fileencoding

File encoding (''=no encoding, 'base64'=Base 64)

int $overwriteifexists

Overwrite file if exists (1 by default)

int $createdirifnotexists

Create subdirectories if the doesn't exists (1 by default)

int $position Position
string $cover

Cover info

array $array_options

Array for extrafields of ECM index table

int $generateThumbs

1=Will generate the small and mini thumbs if applicable

Return Value

string

Exceptions

RestException
RestException
RestException
RestException

array delete(string $modulepart, string $original_file)

Since: 11.0.0 Initial implementation

Delete a document

Parameters

string $modulepart

Name of module or area concerned by file download ('product', 'project', 'project_task', ...)

string $original_file

Relative path with filename, relative to modulepart (for example: PRODUCT-REF-999/IMAGE-999.jpg)

Return Value

array

Success code

Exceptions

RestException
RestException
RestException
RestException
RestException