Documents Class Reference

API class for receive files. More...

Inheritance diagram for Documents:

Collaboration diagram for Documents:

Public Member Functions
	__construct ()
	Constructor.
	index ($modulepart, $original_file='')
	Download a given document.
	builddoc ($modulepart, $original_file='', $doctemplate='', $langcode='')
	Build a document.
	getDocumentsListByElement ($modulepart, $id=0, $ref='', $sortfield='', $sortorder='', $limit=100, $page=0, $content_type='', $pagination_data=false)
	List all documents of an element.
	post ($filename, $modulepart, $ref='', $subdir='', $filecontent='', $fileencoding='', $overwriteifexists=0, $createdirifnotexists=1, $position=0, $cover='', $array_options=[], $generateThumbs=0)
	Return a document.
	delete ($modulepart, $original_file)
	Delete a document.
Public Member Functions inherited from DolibarrApi
	__construct ($db, $cachedir='', $refreshCache=false)
	Constructor.

Additional Inherited Members
Protected Member Functions inherited from DolibarrApi
	_checkValForAPI ($field, $value, $object)
	Check and convert a string depending on its type/name.
	_checkValExtrafieldsForAPI ($field, $value, $object)
	Check and convert a string depending on its type/name.
	_filterObjectProperties ($object, $properties)
	Filter properties that will be returned on object.
	_cleanObjectDatas ($object)
	Clean sensitive object data @phpstan-template T.
	_checkFilters ($sqlfilters, &$error='')
	Return if a $sqlfilters parameter is valid Function no more used.
Static Protected Member Functions inherited from DolibarrApi
static	_checkAccessToResource ($resource, $resource_id=0, $dbtablename='', $feature2='', $dbt_keyfield='fk_soc', $dbt_select='rowid')
	Check access by user to a given resource.
static	_forge_criteria_callback ($matches)
	Function to forge a SQL criteria from a Generic filter string.

Detailed Description

API class for receive files.

Since

6.0.0 Initial implementation

@access protected ,external}

Definition at line 40 of file api_documents.class.php.

Member Function Documentation

builddoc()

Documents::builddoc	(		$modulepart,
			$original_file = '',
			$doctemplate = '',
			$langcode = '' )

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

Since

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

18.0.0 Added support for contract and suppliers invoice documents

19.0.0 Added support for shipment documents

20.0.0 Added support for mrp documents

23.0.0 Added support for expense report documents

23.0.0 Added support for product documents

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).

Returns

array List of documents @phan-return array{filename:string,content-type:string,filesize:false|int,content:string,langcode:string,template:?string,encoding:string} @phpstan-return array{filename:string,content-type:string,filesize:false|int,content:string,langcode:string,template:?string,encoding:string}

@url PUT /builddoc

Exceptions

RestException	400 Bad value for parameter modulepart or original_file
RestException	403 Access denied
RestException	404 Invoice, Order, Proposal, Contract or Shipment not found
RestException	500 Error generating document
RestException	501 File not found

Definition at line 174 of file api_documents.class.php.

References $conf, dol_check_secure_access_document(), dol_mimetype(), dol_osencode(), and getDolGlobalString().

delete()

Documents::delete	(		$modulepart,
			$original_file )

Delete a document.

Since

11.0.0 Initial implementation

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)

Returns

array Success code @phan-return array{success:array{code:int,message:string}} @phpstan-return array{success:array{code:int,message:string}}

@url DELETE /

Exceptions

RestException	400 Bad value for parameter modulepart
RestException	400 Bad value for parameter original_file
RestException	403 Access denied
RestException	404 File not found
RestException	500 Error on file operation

Definition at line 1091 of file api_documents.class.php.

References $conf, dol_check_secure_access_document(), dol_osencode(), and dol_syslog().

getDocumentsListByElement()

Documents::getDocumentsListByElement	(		$modulepart,
			$id = 0,
			$ref = '',
			$sortfield = '',
			$sortorder = '',
			$limit = 100,
			$page = 0,
			$content_type = '',
			$pagination_data = false )

List all 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

Since

7.0.0 Initial implementation

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*

Returns

array Array of documents with path @phan-return array{data:array<mixed,array{name:string,path:string,level1name:string,relativename:string,fullname:string,date:string,size:int,perm:int,type:string}>,pagination:array{total:int,page:int,page_count:int,limit:int}}|array<mixed,array{name:string,path:string,level1name:string,relativename:string,fullname:string,date:string,size:int,perm:int,type:string}> @phpstan-return array<array<string,int|string>>

@url GET /

Exceptions

RestException	400 Bad value for parameter modulepart, id or ref
RestException	403 Access denied
RestException	404 Object (Thirdparty, User, Member, Order, Invoice, Proposal...) not found
RestException	500 Error while fetching object
RestException	503 Error when retrieving ecm list

Parameters

array{name:string,path:string,level1name:string,relativename:string,fullname:string,date:string,size:int,perm:int,type:string,content-type?:string}

$fileitem Item to check for content type (for filtering)

Returns

bool True if file matches a content type

Definition at line 463 of file api_documents.class.php.

References $id, $object, checkUserAccessToObject(), dol_dir_list(), dol_mimetype(), and getMultidirOutput().

index()

Documents::index	(		$modulepart,
			$original_file = '' )

Download a given 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).

Since

7.0.0 Initial implementation

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)

Returns

array List of documents @phan-return array{filename:string,content-type:string,filesize:false|int,content:string,encoding:string} @phpstan-return array{filename:string,content-type:string,filesize:false|int,content:string,encoding:string}

@url GET /download

Exceptions

RestException	400 Bad value for parameter modulepart or original_file
RestException	403 Access denied
RestException	404 File not found

Definition at line 72 of file api_documents.class.php.

References $conf, dol_check_secure_access_document(), dol_mimetype(), dol_osencode(), and dol_syslog().

post()

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

Return a document.

Parameters

int

$id

ID of document

Returns

array Array with data of file

Exceptions

RestException

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

Since

6.0.0 Initial implementation

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

Returns

string

@phan-param array<string,string> $array_options @phpstan-param array<string,string> $array_options

@url POST /upload

Exceptions

RestException	400 Bad Request
RestException	403 Access denied
RestException	404 Object not found
RestException	500 Error on file operation

Definition at line 743 of file api_documents.class.php.

References $conf, $object, dol_basename(), dol_check_secure_access_document(), dol_delete_file(), dol_is_dir(), dol_is_file(), dol_mkdir(), dol_move(), dol_sanitizeFileName(), dol_sanitizePathName(), dol_syslog(), dolCheckVirus(), dolChmod(), get_exdir(), getDolGlobalInt(), getDolGlobalString(), getUserRemoteIP(), image_format_supported(), and isAFileWithExecutableContent().

---

The documentation for this class was generated from the following file:

• dolibarr_dev/htdocs/api/class/api_documents.class.php