Dolibarr ERP CRM Wiki - User contributions [en]

Language and development rules

2021-03-15T07:27:34Z

ALSOFT: /* Index performance */

[[de:Sprachen_und_Programmierregeln]]
[[fr:Langages_et_normes]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDevEn}}

These are some rules on language, syntax and norm we use in the Dolibarr project:

=Versions=

*Dolibarr must work on:

#All OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Must work with no need of complementary PHP module, except module to PHP module to access database).
#MySQL {{MySqlMinVersion}}

=Copyright Norms=

*All PHP files must start with a header that looks like

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
When you edit an existing file of project, you must add a Copyright line under others.

=PHP Norms=
==PHP==

*Dolibarr is written with PHP and supports all versions of PHP higher than {{PHPMinVersion}}. All files must end with extension .php

*Usage of PHP superglobals variables must use the dedicated operators $_COOKIES, $_SERVER, $_ENV but use the Dolibarr function GETPOST() to get the contents of $_GET or $_POST..

*Other operators ($HTTP_SERVER_GET, ...) are now deprecated in PHP, so they must not be used. Code must work if option '''register_long_arrays''' is set to off. Moreover, the code must work when PHP option '''register_globals''' is off (recommended by PHP). It must also work if the option '''register_globals''' is on (by default on a lot of installations).

*Do not use '''<s>PHP_SELF</s>'''. Use instead '''$_SERVER["PHP_SELF"]'''. Also, Dolibarr framework sanitizes content of $_SERVER["PHP_SELF"] variable (into main.inc.php file, before any business code).

*When several variables must be initialized with the same value, you must use individual declarations (separated by ;)

<syntaxhighlight lang="PHP">
$var1 = 1;
$var2 = 1;
$var3 = 1;
</sousyntaxhighlightrce>
instead of
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
which is slower.

<br />

====Strings====

*Strings must be have variables outside of the quote.

<syntaxhighlight lang="PHP">
print "My text show my ".$variable." !\n";
</syntaxhighlight>

<br />

====Comments====

*Comments must use the C syntax, ie a double slash for a comment on one line and a slash-star to open a bloc for several lines

<syntaxhighlight lang="PHP">
/* Bloc of comment
*
* End of bloc
*/

$monobjet = new MonObjet($db);
$result=$monobjet->fetch($idobject);

for ($i = 1 , $i < 2 ; $i++) {
// comment on one line
print $i;
}

function myFunction($param1, $param2)
{
// code
}
</syntaxhighlight>

<br>

*Functions must return a value equal or higher than 0 if successful and strictly lower than 0 if error.

*No dead code (code never used) into Dolibarr core code (code used by external modules only must be included within the external modules).

*Use "include_once" for anything with functions or class definitions in it (like *.class.php and *.lib.php files), use "include" for template-style php with files containing common part of HTML and PHP code (like *.inc.php and *.tpl.php files).

*Coding style to use is the '''PSR-12''' (https://www.php-fig.org/psr/psr-12/). Only rules tagged "MUST" are currently required. So note however the exceptions:
**Length of line: PSR-12 mention we can't go up to 120 characters on same line, this is a soft limit. It is better to have long lines instead of long page with code content that is just data declaration and does not contain any logic. However, we introduced a hard limit of '''1000''' characters (having line larger than this may return errors on Continuous Integration tests).
**Tabs are allowed: The other exception is that we don't replace systematically the tabs with spaces. Using tabs is more convenient for most editors/developers. Also using spaces breaks some auto-format features (like Eclipse autoformat feature on some Eclipse version). For the moment, the best setup is "Keep spaces/tabs as it is", however, you can activate the option "Remove spaces at end of lines".
**We allow elements of an array on same line and we do not always add a new line at end of each element.
**Note 1: The following rule are very important to follow:
***Files must be saved with Unix format (LF) and not Windows (CR/LF). Unix format is compatible on all OS such as Unix like, Windows, Mac, but the Windows text file format may not work on some PHP under Unix.
***Smart tags PHP are not used. PHP code section must start with '''<?php'''
**Note 2: You can use the file '''dev/setup/codesniffer/ruleset.xml''' as rule file to control coding style with PHPCodeSniffer.
**Note 3: You can use the file '''dev/setup/eclipse/PSR-12 [built-in].xml''' as rule file to setup Eclipse syntax formater.
**Note 4: You may note that current code is not yet compliant with the PSR-12. The reason is that we must "now" follow the "MUST" rules of PSR-12, but it wasn't in the past. So feel free to change coding style to match new rules (keep in mind the 2 exceptions) if you find such cases.

==Classes and properties structures==

Some properties of classes are found in different classes. To avoid having different names, we will use the following PHP properties names:

{{TemplatePHPFields}}

=SQL rules=

==DDL file format==
Files containing definition of the database structure (DDL files) must be '''2 per table''':

*The first file defines the table and its fields. The file name contains the table name, e.g. like this: <tt>llx_''mytable''.sql</tt>

A comment will be added for each field to explain its usage.

*The second file defines all foreign keys, performance indexes or other constraints and the file name will be like: <tt>llx_''mytable''.key.sql</tt>

These files must be stored in the directory '''install/mysql/tables''' for all standard files or '''mymodule/tables''' for tables provided by an external module.

Example: '''file for creating the table llx_mytable will be llx_mytable.sql''':

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2013 Author <email@author.com>
--
-- This program is free software; you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation; either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program. If not, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_mytable
(
rowid integer NOT NULL AUTO_INCREMENT PRIMARY KEY,
ref varchar(30) NOT NULL, -- object reference number
entity integer DEFAULT 1 NOT NULL, -- multi company id
ref_ext varchar(255),-- reference into an external system (not used by dolibarr)
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
datec timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,, -- creation datetime
tms timestamp, -- update time stamp
fk_user_author integer NOT NULL, -- Author, foreign key of llx_user
fk_user_mod integer NOT NULL, -- Last updater, foreign key of llx_user
import_key varchar(14) -- Use by import process
)type=innodb;
</syntaxhighlight>

Example: '''file for creating keys/indexes for the table llx_mytable will be llx_mytable.key.sql''':

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2013 Author <email@author.com>
--
-- This program is free software; you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation; either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program. If not, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_mytable ADD UNIQUE uk_mytable_field (field_one, field_two);

ALTER TABLE llx_mytable ADD CONSTRAINT fk_mytable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Table and fields structures==

*Structure of tables.

When you create a new table, it is recommended to use the same conventions as other Dolibarr tables. This means the following fields:
- rowid INTEGER AUTO_INCREMENT PRIMARY KEY that is technical id of record
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- tms timestamp that will contain date of last modification (the database manages this field automatically, no need to manage it by the code, just create the field)
- date_valid datetime that is the validation date (if applicable)
- import_key varchar(32) that will contains the import code YYYYMMDDHHMMSS if you make mass import.
- status smallint to store a status
Eventually
- fk_user_creat or fk_user_author integer that is the id of user making creation
- fk_user_modif integer that is the id of user making change
- fk_user_valid integer that is the id of user validating record (if applicable)
- fk_soc integer that is the ID of the Third party (if applicable)

Note field:
- note_private text for private comment of the object
- note_pubic text for public comment of the object
or
- note text if there is no need to have private and public

*Type of fields:

Well, to be compatible with any accuracy required by any country on amounts, to be compatible with any database syntax and with the Dolibarr upgrade framework, we will use the following types for database fields:

- integer for a primary key, an integer or any of foreign key (bigint may also be accepted for very large tables)
- smallint for a small number (like for a status) or a boolean
- double(24,8) for any amount
- double(6,3) for any vat rate
- real for a quantity
- varchar for a string (also if length is 1, the type char is more and more deprecated)
- timestamp for a field date+time that is automatically updated
- datetime for a field date+time
- date for a field date
- text or medium text for large fields (no index allowed on such fields)

All business rules must be on same place, into PHP code, not into client, neither into database, that's why type enum is also not allowed.
Other type are not allowed for compatibility reasons.

*All tables has a prefix to avoid name conflicts with other projects. In current version this prefix is fixed ans can't be modified. Its value is <tt>llx_</tt>. In a future version this value should be modified during installation process.

==Primary keys==
The primary key of a table must be called <tt>rowid</tt>.

Some old tables does not use this rule and use a primary key called <tt>id</tt> (ie [[Table llx_c_actioncomm]]), but the reason is history and this should not happen anymore.

==Foreign keys==
Name of a foreign key must start with the prefix <tt>fk_</tt> followed by the table name (i.e. name of the referencing table) (this is required to avoid duplicate names in project that are not allowed even if in different tables by some DBMS like Postgresql) then the field name (i.e. name of the referencing field) (this is to allow to have several foreign keys in same table).

Example:
''fk_facture_fourn_fk_soc'' is a foreign key in the table llx_facture_fourn for the field fk_soc in this table (that references the rowid field in another table)

Note: If you develop your own external module, it must have no foreign keys that point to Dolibarr standard tables. This will break standard dolibarr upgrades, repair, backup and restore tools and may also break standard features.

==Alternative keys==
Sometimes, we need another unique keys than primary key. We can add in this case an alternate unique key. When we need this, we can create an alternate unique key. Such an index is called by a name that start by prefix <tt>uk_</tt> followed by an underscore, then the the table name (this is required to avoid duplicate names of unique keys that may create problems for some DBMS like Postgresql) and then another string to define the key (this is to allow to have several unique keys on same table).

Example:
''uk_societe_code_client'' is a unique key on table llx_societe on field code_client.

==Index performance==
Some fields are often used as search or order criteria, or for joins. In such case, we need to set a performance index on field to increase performances. Such indexes are named with a prefix <tt>idx_</tt> then the table name and then the field name.

Example:
''idx_societe_user_creat'' is a performance index on table llx_societe for field user_creat

==SQL Coding rules==

*Alias usage/Fields naming

When doing select, we can use alias to simplify writing/reading of requests:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
However, we must not used alias for update request as they are not compatible with Mysql 3.1.

*Using SELECT * is forbidden ! When using SELECT you must define complete list of fields to get. This avoids confusion. And above all, this make reengeering of code easier and make impact analysis of change on a field possible. Example:

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*Into SQL requests, you must quote fields except the fields that contain amounts which must be stored as double or real type. Quotes on numbers may result in saving as a different value. For example 412.62 in an insert will be saved as value 412.61999512 into database (due to implicit conversion string to numeric) if the target field has type double(24,8). Only PHP see value 412.61999512. Other tools will see 412.62 giving a sense that there is no problem. But it's PHP that has the good vision. There is really a wrong value into database. By removing quotes on numbers, no problem occurs.

Example:
<syntaxhighlight lang="sql">
Good: INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', 412.62)
Bad: INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', '412.62')
</syntaxhighlight>

Note, problem of float numbers is same problem on all langauges and not only when inserting data into database. It occurs also with any language when you work on "real" numbers, so numbers must be, as soon as they are affected, cleaned with function price2num with second parameter defined to :
'MU' (for unit prices), 'MT' (for total prices) or 'MS' (otherwise) depending on usage of number. (see function documentation)

*Functions NOW, SYSDATE or DATEDIFF are forbidden inside SQL requests. If you must use the current date into a field, value must come from the PHP and not from the database engine. This is for better portability of code and correct management of TimeZone.

For example, don't do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
but do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

For example, don't do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
but do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

An other advantage of this rule, is that request benefits of index because we are making a compare of a field with a fixed value. When using datediff, you make an operation on field before comparison, this means database can't use the index on field, resulting on very bad performance compared to solution without the datediff.

*Use $db->ifsql for SQL IF

Do not include the IF into your forged SQL request. But use instead $db->ifsql() method to you will make a SQL IF that is compatible with all SQL databases.

==Using Database triggers==
Using Database triggers is not allowed into the code of Dolibarr, so you should have no troubles with Database triggers.
Database triggers are not portable. Compatibility may be broken when upgrading your version of your database, database triggers are often not included into backup tools, database triggers need permissions that you may not have (and should not have) on a common secured database, database triggers means also that you include some "business rules" of your application into the database where most other rules are managed by the code itself creating conflict or code that can't be debugged with a step by step debugger, ...
There is tons of reason why we do not recommand to use database triggers in your own development.
Using Database triggers can save you time when you make development but is a very bad practice, so is forbidden as it is not compatible with the high level of quality of code expected by Dolibarr team. External modules that uses Database triggers may also be refused on the market place since it won't work for more than 50% of users.

==MySQL-MariaDB specificity==

*Tables must be declared with format InnoDB.

This format supports foreign keys and their restrictions, and transactions integrity is also supported. This guarantees that Dolibarr events keep all data with correct values between tables even when transaction modify different tables.

*Dolibarr MUST work even if MySQL option '''strict''' is active.

To activate it (required when developing on Dolibarr), add the following line into the config file of your MySQL server (my.cnf or my.ini)
{{MySqlStrictMode}}

==PostgreSQL specificities==
Only MySQL files must be maintained.
Those files are converted "on the fly" by the database Dolibarr driver.

There is an exception for the SQL "UPDATE FROM":

MySQL Syntax:
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

PgSQL Syntax:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

There is no native SQL requests "UPDATE FROM" in all Dolibarr core. But if you use one in your own code of your module, you should do :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=HTML norms=
==Syntax rules==

*HTML used must be HTML compliant and not XHTML. All attributes of HTML tags must be in lower case and quoted with ".

*Links href must be absolute and use the function dol_buildpath() to get absolute path from a relative path and img tag must be build using function img_picto().

For example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/mydir/mypage.php').'">'.img_picto('Texte alt','namepictopng','').'</a>';
</syntaxhighlight>

*HTML tables must have columns with no forced width, except for columns that contains data we know the length. For example, a column with a picto only can be forced to with="20px".

Otherwise, we must avoid forcing the column width. Reason is that, in most cases, the browser make a better works to define column width automatically than forced values, and it works whatever is the resolution.

*Javascript/ajax code and call to javascript files into php pages must be avoided. However, if you need to include javascript code, you must add a condition on "$conf->use_javascript_ajax"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // php code generating javascript here
}
</syntaxhighlight>

*Popup windows must not be used, except for tooltips (and must have a condition as explained before).

*External scripts must be written in Perl if they can't be written in PHP. Usage of another language is not forbidden but must be argued before in the development mailing-list.

==External templating framework ?==
There is ton of frameworks to provide a templating language of an HTML page. The best and faster is just called "PHP", and because Dolibarr already depends on PHP, there is no need to introduce a dependency on a third language.

All templating frameworks are just preprocessor, BEFORE PHP. It can't be faster than PHP alone. When we say "speed is increased because templating framework use a cache", you must read in fact "the overtime spent by the framework is reduced by cache, not the speed of processing PHP file". We should say "any templating framework has an overload over PHP, the cache of the templating framework just reduces the slowing effect of using this framework", but not "the speed is increased, it is always decreased compared to pure PHP".

Above all, having a templating system is completely possible by doing a "'''.tpl.php'''" file that dos not contains any logic code, but only HTML and "echo". We get same result (but faster and easier to develop because it does not need to do all the setXXX before calling each template). All variables (known by code that include the template) are automaticaly known into a PHP template page. No risk to forget a set, and a lot of line of codes reduced, a lot of time and development errors are also saved.

Also, keeping a 100% isolation between code and HTML output is interesting in only 1 situation: When teams building design is complety different than team building logic code, AND if you build not too sophisticated pages, AND with no need of too many Ajax features (this need to know how code works).
And this situation is surely not the Dolibarr future (team will often be same, Ajax will be more and more present, event if I hope not too much, and screens are more and more dependent of dynamic or contextual events, difficult to have this with one simple template without transforming the template into a page with high level of code).

There is a ton of other reasons to not use an external templating system and all arguments to use them are also the best argument to use PHP as our templating system.

=Dolibarr norms and code skeleton=

==Skeleton code==
To standardize the code, and to speed up the development of new components in Dolibarr, you'll find skeletons of files fully prepared in the directory '''htdocs/modulebuilder/templates/'''.

For example:

*1 file that serves as an example of the module description: '''myModule.class.php'''
*1 file that serves as an example of code for creating a new class: '''skeleton_class.class.php'''
*1 file that serves as an example of code for creating a new page: '''skeleton_page.php'''
*1 file that serves as an example of code for creating a script for executing command lines: '''skeleton_script.php'''

...

Use it as an example.
Note that the skeletons are also used by the PHP Code generator ([[Module ModuleBuilder]]), which is described in the development chapter of Dolibarr modules, to speed up your development.

==Dates and Timezones==
Dolibarr is an application that is multi-user and multi-location. It's therefore necessary to store dates in the right format. To avoid problems with conversions, the following rules should be applied:

*A date into memory must always be stored with Timestamp GMT format.
*A date stored into database, is the GMT Timestamp of date submitted into the request usng the <b>PHP server</b> timezone. This does not apply to date update automatically by database (fields '''tms''' into database).

For exemple le 1st january 1970, 3 hour at Paris (TZ=+1) = 2 hour at Greenwitch (TZ=0) will be stored into memory with value 7200 and will be submitted into a SQL request to database with the string '19700101030000' (PHP convert into its TZ hour and database will unconvert it using its timezone too that is same than PHP).

All select methods should translate date fields, that are with format TZ of database ('19700101030000'), into a timestamp field by calling the method db->jdate. This is to store into memory a GTM Timestamp date. All insert methods must convert, during generation of SQL request, the memory date into the string by using db->idate (you may find examples into skeleton).

*Dates that are updated automatically (field '''tms''' into database) contains a GMT Timestamp GMT of date when change is done. The select will also use the db->jdate (that use PHP server TZ) to convert read data into a GMT Timestamp into memory. So if timezone of database differs from timezone of PHP server (one of them is not correctly set), you may experience differences between creation date and update date.

*Manipulation date with PHP must be done using the Dolibarr date functions: '''dol_now(), dol_mktime(), dol_stringtotime(), dol_getdate(), dol_time_plus_duree()'''. You may also find other functions available into file '''date.lib.php'''.

==UTF8/ISO encoding==
Dolibarr stores data in the following way:

*In database, data is stored in UTF8 or ISO. It depends on the database's pagecode therefore these options are set at creation time. In any case, Dolibarr's database driver (in lib/database) deals with it to convert from/to UTF8 at insertion and readout.
*Memory data is stored in UTF8 (PHP object instances).
*Web pages are returned and rendered into UTF8

==Float numbers, amount and calculation==
With PHP, like other languages (Java for exemple), non integer data (float, real, double) are not reliable for calculation.
Try to make for example
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
You wont get zero but a very small decimal number. If you get zero her, you should be able to find other examples that don't work.
Problem of float is general, so a variable that is a result of a calculation using decimal numbers must ALWAYS be cleaned using the function '''price2num()''' with the econd parameter to: 'MU', 'MT' or 'MS' depending on need (see description of function).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
If data manipulated is not an amount, then using MU, MT, MS has no sense, and you must use the function '''round()'''.

==Creation of tables==
Do not create tables, on the fly, during execution by a standard user, we mean, during current usage of software.
If you create a module that uses its own table, not available in the default Dolibarr code, then take a look at tutorial [[Module development]]. It explains how to provide new tables with your module, so that, the tables will be created during module activation and not during module usage.

==Comparing version==
If your code need to make different things depending on Dolibarr version, you can use the following tip to detect and compare versions
<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

But this solution need to include the function versioncompare. An alternative solution to test version is to do:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Add logs to your code using function
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==Working directory==
If you need to create a working directory, into your code, refer to it with
'''DOL_DATA_ROOT.'/mymodule''''

The directory can be created into your code by the following function:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/mymodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

If you need a directory to store temporary data, this directory must be '''DOL_DATA_ROOT.'/mymodule/temp''''

=Design patterns and Object programming=

==Creation design patterns (GoF)==
Design patterns defined by the Gang Of Four (see wikipédia on [[w:Design patterns|Design patterns]]).
No usage of such patterns is required. We found some objects next to Singletons or Factory but not completely compliant with syntax, this is to be compatible with PHP 4 that is not a pure object language.

==Structure design patterns (GoF)==
Design patterns defined by the Gang Of Four (see wikipédia on [[w:Design patterns|Design patterns]]).
No usage of such patterns is required.

==Behavior design patterns (GoF)==
Design patterns defined by the Gang Of Four (see wikipédia on [[w:Design patterns|Design patterns]]).
No usage of such patterns is required.

==Design patterns of enterprise (Martin Fowler)==

===Patterns of code organization===
[[w:Martin Fowler|Martin Fowler]] has identified 3 ways to organize code:

*The '''Transaction Script''' (The source code is linear for each user action).

This is the old school used by all procedural languages.
Inconvenient: Redundancy of code. Need to know the physical model of data to develop.

*The '''Domain Model'''

This notion is available with object languages. It is business process (to identify before) that are used for objects classes.
Inconvenient: Model very complex to maintain.

*The '''Table Module'''

This is a mix between 2 previous where we have only one unique class for each table of database.

-> As shown in code skeletons (see previous chapter), Dolibarr uses concept of '''Table Module'''.

===Communication between business logic - data (ORM)===

There are 3 ways to make links:

*The '''Table And Row Data Gateway'''

This is the most simple. You have one class per table and each class is a link to the table with CRUD methods (Ceate, Read, Update, Delete). A class instance is a record in the table. The class contains only code to reach lines and fields of table.

Example: This mode is used by some ORM Frameworks, like '''iBatis''' (http://ibatis.apache.org/).

*The '''Active Record'''

Same as previous, but we are allowed to add some business functions into the class, if such functions are dedicated to the table or recording into this table.

Example: This mode is used for Dolibarr development and most PHP software that includes their own framework and best practices.

*The '''Data Mapper'''

Classes represent entities of the problem and not the data. So you have to double, triple ... these classes with Mapper classes to access the data.
More "purist" on paper (closer of business), this method also has the disadvantage of being more complex in practice.

Example: This is the choice if you use the ORM Framework '''Propel''' (http://propel.phpdb.org/trac/). We find this model in heavier applications, based on this ORM among others.

-> For Dolibarr development, it is recommended to use the connection mode '''Active Record''', which offers the advantages of a model close to the business without having the complexity, without obfuscating technical architecture. It is by this way that the development, understanding of code and technical maintenance and / or business behaviour seems the more productive (this is however an ongoing debate between the purists and the pragmatists, debate in which nobody can really be right, because it depends on the objectives).
[[Category:Development]]

==Design pattern for Graphic interfaces (MVC)==
There are several design patterns for user interfaces (MVC, MVP, MVVM).
Many confuse this design pattern with that of using a template framework. It's unrelated. A template framework (see previous point) is only linked to the "V" part of these models.

-> Dolibarr uses the '''MVC''' Design Pattern. Part M is materialized by a DAO class containing the CRUD (Create-Read-Update-Delete) methods for accessing the table.
Many frameworks have chosen to put the C code part (Controller) and the V code part (View) in different files, or even separate directories. The maintenance seems easier on paper, in practice, you have to juggle constantly between a ton of files when your project become larger. In Dolibarr, the separation is made by a simple comment section. The part of code C (Controller) is therefore the code that follow the tag
<pre>
/*
* Actions
* /
</pre>
It is followed by the part of code V (Vue), well separated from the C by the tag
<pre>
/*
* View
* /
</pre>

This mode of separation has had a neutral effect on new developments but has made it possible to reduce the time required for maintenance and fixing bugs so significantly that it is not envisaged to switch to another type of separation (yes the findings made in real life are not always those expected by school theory). The important thing remains that there is always a separation between C and V, no matter how this separation is materialized, as long as it is (Reminder: Do not confuse the notion of separation of C and V with the notion of separation of the code to feed the data of a View and of the code to format the View, this a principle of separation relating to the Design Pattern of Vue, see next point).

==Design pattern for Views - Presentation==
There are frameworks that specialize in Vue Design Pattern, the part of formatting the screen seen by the user.
Old versions of Dolibarr used Smarty. This framework is an overlay to an already very powerful screen formatting framework called ... PHP. The benefits being much lower than the disadvantages, it has been abandoned in favor of PHP templates (.tpl.php file) which remain the simplest, the most universal, the most scalable and the most efficient, of the presentation frameworks.

Its only flaw is that it cannot guarantee 100% the deviations of a developer who would integrate into the View, a logic unrelated to the presentation (therefore other than code intended for generation, formatting, HTML output , test or loop logic). This point is however controlled by the validation mechanism of the project managers' code.

Here again, it is the experience and the observation of a better productivity performance that has motivated the abandonment of the external Presentation frameworks in favor of the PHP framework.

Module development

2021-03-10T12:21:22Z

ALSOFT: /* Add your own permissions (optional) */

[[fr:Développement_module]]
[[es:Desarrollo_de_un_módulo]]
[[de:Modul_Entwicklung]]
[[zh:模块开发]]


[[Category:Core]]
{{TemplateDocDevEn}}

To create a new module/addon for Dolibarr, there is several steps. This tutorial will describe you each of them to build a module to extend Dolibarr features, like one or several of the following :

*Add new tables in database
*Add your own menu entries
*Add new screens to edit new tables
*Add or remove tabs on object view (invoice, product, order, event, ...)
*Add predefined exports for the internal export tool
*Add new information boxes in the home page
*Add new substitutions variables
*Define new permissions
*Execute code automatically triggered by a particular Dolibarr action
*Insert your code inside Dolibarr hooks positions
*Add your numbering module
*Add a new document template
*Add a new skin

etc...

Following chapters presents how to do all of this manually with an easy way.

=Module creation with the module builder=
From Dolibarr 9.0 it is possible to create the main pages of your module with the Module Builder. To activate it, go into the list of module and enable the module "Module Builder", then click on the "bug" image in the top right of screen.

=Example of Template External Module=
A good model to start development of external module can be found here : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

=Create your module=
==Create a Module descriptor for your Module (required)==
'''When it is required''': Required as soon as an addon is developed, whatever its goal is (except for adding a skin).

'''Since Dolibarr 9.0, you should use the ModuleBuilder module provided as a standard module to generate the module descriptor'''

===Create your module descriptor===
The first step is to create a file descriptor for the module.

*Create directory '''/htdocs/''mymodule''/core/modules'''. Then copy the file modMyModule.class.php from the directory dev/skeletons into this directory '''htdocs/''mymodule''/core/modules'''. Change the name of the file modMyModule.class.php to the name corresponding to the purpose of your module. Name of the file must start with initial 'mod' and end with .class.php (for example if you want to give the name 'NewName' to this file, then the name should be 'modNewName.class.php').

Next modify the contents of this file as follows:

*Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contain only alpha characters (again, if the name given to the file was 'NewName', then replace all "modMyModule" with "modNewName").
*Change the number in: $this->numero = 100000 by a number that designates your module id. To avoid conflicts with other modules, you can consult the page that lists already reserved id numbers: [[List of modules id|List of modules id]].
*Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).

Your file descriptor for your module is ready. See the next step to activate it.

===Test your descriptor===

Launch Dolibarr and go to page '''Setup->module'''?
If you set the property version in the module description you should see a new line with your new module and the possibility to activate it or not. If you set the property version to "develop" or "experiental", to see your module, you must first go into '''Setup-Others''' and set MAIN_FEATURES_LEVEL to 1 to see "experimental" modules or 2 to see "development" modules.

==Tree of path for new module files (required)==
This is how your files must be organized when building a new module (the zip file must also match this rule).
Note: Only the second line is mandatory.

{{TemplateModuleTreeSimple}}

==Create your SQL tables and the PHP DAO class (optional)==
'''When''': If your module needs to manage data of its own

===Create your .sql file===
If your module is designed to manage data of its own, which are not available in the standard version of Dolibarr, it is necessary to define SQL tables to store the data.

Scripts for creating tables and load data by your own module are saved into a subdirectory called "/mymodule/sql".

Then check into your descriptor file, into function '''init''' that the line

<source lang="php">$this->_load_tables('/mymodule/sql/');</source>

is not commented.

''Rules to follow:''

*Add the files about creating tables commands on the principle of a file '''llx_matable.sql''' per table, with a possibly file '''llx_matable.key.sql''' (see existing files in '''install/mysql/tables''' for examples).
*The recommended type and name for SQL fields are defined into page [[Language_and_development_rules#Table_and_fields_structures]].
*To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
*Don't use the double quote for strings (eg 'chaine' not "chaine") because the double quote have a specific meaning in PostGreSQL

Example of content of a file data.sql
<source lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</source>

Files must be operational for the database mysql. Rem: The files of other databases are not maintained. They will be read and converted on the fly by the driver of the other database.

===Test your .sql files===

Once the files ready, you can return to Dolibarr to disable the module, drop those tables in the database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.

===Generate the PHP DAO class===
Once you have created your tables into the database, move to the dev/skeletons directory and run the script

<source lang="bash">php build_class_from_table.php tablename modulename</source>
Note: If the command does not work, try to use php-cli php instead.

This will generate a file '''out.tablename.class.php''' that contains the class to manage table tablename.
In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table.
Remove just the "out" from the file name and put the file in a subdirectory of '''htdocs''' specific to your module (in htdocs/mymodule for example).

A file '''out.tablename_script.php''' has been generated and contains a sample code to use the class for each of the 4 CRUD methods.

'''Since Dolibarr 6.0, the file dev/skeletons/build_class_from_table.php is no more provided. To build a class from a table you should use the ModuleBuilder modules provided as a standard module.'''

==The tab management (optional)==

===Add or remove your own tabs on object sheets===
'''When''': To add a tab on an object (invoices, orders, proposals, member ...)

To do this go into the file descriptor of module previously created and edit the $this->tabs array:

<source lang="php">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</source>

The table should contain a list of strings, each string representing a new tab.
The format of the string consisting of 5 parts separated by ":"

*Part 1: The element type (object type) where the tab should appear is a value from the following:
{{TemplateModuleTabs}}

*Part 2: A code to identify tab to add (start with +) or to remove (start with -)
*Part 3: The title of the tab. This can be a hard read or better code translation in a file lang.
*Part 4: The name of the file "*.lang" which contains correspondence between the code translation and language to display. If this name is followed with @mymodule, Dolibarr will search translation file "*.lang" within the module, so htdocs/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mylangfile.lang
*Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
*Part 6: The URL of the page to display when you click on the tab. The __ID__ string will be replaced automatically by the Id of the element concerned.

To feed the contents of the tab with data from the database, see the next chapter.

In order to get the names 'tabname' of existing tabs, you have to check the names used in the function 'product_prepare_head' of the file 'core/lib/module.lib.php' corresponding to section '$head[$h][2]'.

===Show tabs navigation into your own pages===
'''When''': To show all standard tabs of an object (product, tiers, etc.) on your page.

You must follow these steps :

'''1. Include files you need into your file'''

For each object type, there are two files to include with line
<source lang="php">require_once($url_fichier) ;</source>

This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :

*Object thirdparty (thirdparty) :
**DOL_DOCUMENT_ROOT/societe/class/societe.class.php
**DOL_DOCUMENT_ROOT/core/lib/company.lib.php
*Object product (product) :
**DOL_DOCUMENT_ROOT/product/class/product.class.php
**DOL_DOCUMENT_ROOT/core/lib/product.lib.php
*Object invoice (invoice) :
**DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
**DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

...

'''2. Create and load the object to show into your tab'''

Create an instance of an object of the correct class and load object from the database by using the fetch method of an object in providing to this method the id you get from URL (ie : /mytab.php?id=1).

''Example :''
<source lang="php">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
</source>

'''3. Get a list of all tabs to show for your object type'''

Use function XXX_prepare_head($obj), where XXX is name of object. This will return an array with all definition of tab entries to show. The parameter to put into this method is the instance of an object you want tabs.

The resulting array has the following structure
<source lang="php">
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
</source>

''Example :''
<source lang="php">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
</source>

'''4. show tabs into your page'''

Use function dol_fiche_head() to show all tabs defined into array $head returned by XX_prepare_head().

<source lang="php">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
//$links // Tableau des onglets, appelé $head plus haut.
//$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module, ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
//$title // Title to show (shown into a special tab that you can't click)
//$notab
//$picto // Name of image to show into title. Possible values are:
// product
// service
// company
</source>

This function will show required tabs and open an html element ''< div class="" >'' that correspond to the area under the tabs. To close area of a tab, just use ''< /div >'' into your PHP page.

==Create or modify PHP screens (optional)==
'''When''': If the purpose of your module is to add features that require new or modified screens.

===Create a new PHP screen===
You must then create your PHP pages that will show/edit data from tables using the skeleton templates provided as an example in the directory '''modulebuilder/myobject_page.php''' (For the development of a script from the command line, see [[Script development]]).

To create a new user screen, create a subdirectory of '''htdocs''' (if not already done) for your module (in '''htdocs/mymodule''' for example) to store the pages you will create.

Copy, into that directory, the file '''myobject_page.phpp''' that will serve as a starting point for your page file.
Edit the file to have a correct relative path to the main.inc.php file.
<source lang="php">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root calculated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</source>
As you can see, there are several tries to load the main.inc.php (or master.inc.php). The goal is to succeed in the most cases as possible. The minimum is 2 lines: one to try to load the master/main.inc.php into the dolibarr root directory and another one to try to load the file to support the case when the module is deployed into the "custom" directory. But you can have more to deal more situation. The provided example should be able to load the file main/master.inc.php in nearly all situation/setups.

Note that you may add more "../" depending on the depth of the file relative to your module directory tree.

It's in the main.inc.php file that is loaded technical environment variables and permissions. The following variables are objects positioned in this file:

*$user Object that contains the characteristics of the user + his permissions.
*$conf Object that contains Dolibarr configuration.
*$db Object that contains an opened connection handler to the database.
*$langs Object that contains the user's language.

Then enter your code to display the page.

*To include a class or library dedicated to the module is done using a Dolibarr function (and not using directly include_once):

''Example :''
<source lang="php">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
</source>

*To include classes provided with Dolibarr, use the following syntax:

''Example :''
<source lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</source>

===Add some fields into existing forms===
You may want to provide a module that adds more fields into forms (input and view) of some elements.

A heavy solution (but not so bad) may be to replace all pages used to create element (this means to disable the "New element" menu entry and adding yours, and disable tab that shows element to replace with a tab that is your own full page (copied/pasted from original) to do same than original page but modified to add your fields and stored added data into your own table). Go to menu [[#Define your entries in the menu (optional)]] and [[#The tab management (optional)]] if this solution suits you (this solution is more powerful since you can change everything you want into the page).

We will describe here another solution, that works only to "add fields" at end of existing fields, using the element "category" as an example but you can convert this tutorial for invoice, proposal ...

*First thing is to add a table, owned by your module, to store the value of new fields. This table will have only one column called "rowid" (will contain the same value than field rowid of element table) + one column for each new field you want to add. Then create a class with CRUD (Create/Read/Update/Delete) methods for this new table. For this two tasks, go back to previous chapter [[#Create your SQL tables and the PHP DAO class]].
*Next step is to add a hook into your module to add the new fields into the form. See chapter [[Hooks_system#Implement_the_Hook]] for generic documentation to use hooks.

If you follow this tutorial, to be able to add fields into category forms, you must do:
{{ToComplete}}

===Replace parts of screen that are templated (version 3.3+)===
Some parts of Dolibarr screen are isolated into native PHP template files.
You can develop a module to overwrite such templates with yours.
{{ToComplete}}

===Add/replace part of fields supported by hooks===
See chapter [[Hooks_system#Implement_the_Hook]] to know how to use Dolibarr existing hooks to add/replace code at Dolibarr hooks place.

===Database access===
If you need to edit some data in the database inside your own table, use the PHP class generated before.

If you to make access to tables with no dedicated PHP class available, this is always possible (for example if you want to get a list of records with a particular join or filter). In this case, this is a code samples to follow:

To make an insert, update or delete:

<source lang="php">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</source>

To read:

<source lang="php">
$resql=$db->query("My select request");
if ($resql)
{
$num = $db->num_rows($resql);
$i = 0;
if ($num)
{
while ($i < $num)
{
$obj = $db->fetch_object($resql);
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}
</source>

===Define style of your pages===
To have the look of your own pages to match the Dolibarr theme, it is necessary to use the Dolibarr CSS styles.

You can use for example:

*class="'''liste_titre'''" on tags ''tr'' and ''td'' for the head row of a table.
*class="'''pair'''" or class="'''impair'''" on tags ''tr'' and ''td'' of other rows of a table.
*class="'''flat'''" on all input fields (''input, select, textarea''...).
*class="'''button'''" on HTML fields with type ''input type="submit"''.

===Use the Dolibarr date picker===
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
The string mykey will identify the date selector in the form. You must use different values if you use several date selectors in same page.
The string myform is the name of the FORM in which the selector is included (value found in the form name="myform" in HTML page).
This means a date selector must be included necessarily into an html FORM.

To get value after the POST of your form, the command is:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

==Add your own setup page (optional)==
'''When''': If your module needs parameters, which are to be provided by the user, for proper setting up of the module.

===Create your page to edit parameters===
If your module needs several parameters to be setup, you must create a page to edit options (these options will be saved in the [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that shows a form for possible options to update them into the above-mentioned table.
It is necessary to take an example from a page of the directory '''/admin''' that will show you the way to read/save your parameters.
Put this PHP page into the directory '''/admin''' of your module (e.g. mymodule/admin/mymodule_setuppage.php).

===Modify the descriptor file of your module===
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set the name of this PHP page.
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php");
</source>
If the page is in the directory '''mymodule/admin/''', then like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
</source>

===Test your page===
Go into page '''Home->Setup->Modules''', you should see a picture at the end of the line of your module to reach your setup page. Click on it, you should be able to view/edit parameters from your page.

==Define your entries in menu (optional)==
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

===Define your menu entries===
For this, you must define into the module descriptor, the array this->menu that declares all menus added by your module.
This array contains entries that will appear once your module is activated.
The example module descriptor file '''modMyModule.class.php''' contains an example to declare a top menu and also its left menu entries.

This is the example of code to declare your own menu entries in a module descriptor file:
<source lang="php">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'fk_mainmenu=xxx', // Use 'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is mainmenucode and yyy is a leftmenucode of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

To show the menu or not depending on a permission, modify property '''perms''' in the array. See chapter on permissions later to see how to add permissions.

===Test your menu entries===
Disable and re-enable your module under the Dolibarr module setup page, menus entries must appear (if property 'enabled' is declaration array is ok).

==Add your own permissions (optional)==
'''When''': If you want to add new permissions.

The way to define permissions that will manage your module is done inside the module descriptor created previously.
Modify line
<source lang="php">
$this->rights_class = 'mymodule'
</source>
with correct value for mymodule.

Then you must fill the array $this->rights with as many entries than different permissions you need to manage.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][2] = 'r';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</source>

Into $this->rights[$r][0], put a permission id not already used (See into menu '''System info''' on a working installation of Dolibarr to know list of id already used by standard modules.
Into $this->rights[$r][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''' Translation key should be "Permission10001=My permission Label").
Into $this->rights[$r][2], types of the permission. There are three type of permission, 'r' for read, list or expert permission, 'w' for write or update permission and 'd' for delete permission.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any newly created user.
Into $this->rights[$r][4] and $this->rights[$r][5], put an action and subaction string without spaces. You will be able to test if a user has the permission in your PHP source code with the sequence:

<source lang="php">
if ($user->rights->mymodule->action->subaction) ...
</source>

==Define your own box (optional)==
'''When''': If your module needs to provide one or several new boxes to show on home page.

===Define your box===
For this, modify the array $this->boxes into the module descriptor file.
All you have to do is to add 2 lines for each box file you will create into directory '''htdocs/mymodule/core/boxes'''

''Example:''
<source lang="php">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
</source>

Then create files '''htdocs/mymodule/core/boxes/mybox0.php''', '''htdocs/mymodule/core/boxes/mybox1.php'''... by copying an example from an existing box file (found into directory '''htdocs/core/boxes''').

===Test if your box is detected by Dolibarr===
Disable and enabled module.

Go into menu '''Home - Setup - Boxes'''.

Your boxes must appear in the list of boxes you can activate. Activate the box and go on the home page to see if the box is showing correctly.

==Define your own export (optional)==
'''When''': If your module provides new predefined database export profiles (for its own tables or for already existing tables of another module).

===Define export===
For this uncomment and modify arrays $this->export_xxx in your module descriptor file.

===Test your export===
Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled).
Choose it, you must see a list of all possible fields defined in the export arrays.
Choose on field and try to build an export file. If ok, try again with all fields.

==Define your CSS styles (optional)==
'''When''': If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommanded).

===Create and declare your style sheet===
Create a style sheet CSS named '''mymodule.css''' or '''mymodule.css.php''' and put it into directory '''htdocs/mymodule'''. You can have several CSS files per module.
Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file '''themes/mytheme/''themename''.css.php'''. Create your own CSS files only if you need absolutely to add not already existing styles.

Once your style sheets are ready, declare them into your module descriptor file by modifying the property '''$this->modules_parts'''.
Value to put here must be an array of relative URLs to your CSS files.
For example
<source lang="php">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));
</source>

===Test your style sheet===
Disable and enable your module.

Go on the home page (index.php). Show the HTML source of the page.

You should see into the HTML header, a line that declares your style sheet.

==Add your Javascript functions (optional)==
'''When''': If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)

If you need to use your own javascript functions inside your PHP pages, it is necessary to have your functions, defined into your javascript file '''htdocs/mymodule/js/mymodule.js''', included into the HTML HEAD section.
To ask Dolibarr that forge this header to include your own javascript file, you must just provide it to the llxHeader() function called by your page.

Example for page /htdocs/mymodule/mypage.php :
<source lang="php">
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</source>

==Run your own code on any Dolibarr event (optional)==
'''When''': If you want to execute your own code once a common Dolibarr event has occurred (example: I want to update a table in my module when an invoice is created into Dolibarr), you must create a '''triggers'''.

See also [[Interfaces_Dolibarr_toward_foreign_systems]]
and [[Interfaces_from_foreign_systems_toward_Dolibarr]]

==Insert your code inside Dolibarr hooks positions (optional)==
'''When''': When you want to add code or replace Dolibarr code into another situation than a business event (See the previous chapter for adding code during a business event).

See page [[Hooks_system]].

==Add your own numbering rules==
'''When''': When you need a new rule for generated ref of elements that are not covered by existing rules.

See page [[Create numbering module]].

==Add your document template (optional)==
'''When''': When you want to personalized your own generated PDF or ODT documents.

Note: To add this feature you don't need to create a module descriptor.

Documentation to add your own template is available on page [[Create_a_PDF_document_template]] or [[Create_an_ODT_document_template]].

==Add your skin (optional)==
'''When''': When you want to personalized your colors/fonts/images.

Note: To add this feature you don't need to create a module descriptor.

To add your own skin, read page [[Skins]].

=Some coding rules and predefined functions=
The coding rules to be followed are defined in the [[Developer documentation]], under section "General Information - Language and standards development".

A lot of predefined features for developers are also available and described into page [[Developer documentation]] under section "Technical components of Dolibarr".

=Create a package to distribute and install your module=
This process must be used to generate a package to submit it on the http://www.dolistore.com marketplace.
But you can use it to have a package easy to distribute on your own network.

*Go into the directory '''/build''' and copy the file '''makepack-dolibarrmodules.conf''' into '''makepack-mymodule.conf'''. Warning, this directory may not be provided in some packages of stable versions. If so, it can be retrieved from the snapshot available for download on the Dolibarr website in area "Development version" (taken in this case the whole build directory which is autonomous and independent directory).

Edit this file to add a list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

*Run the script via Perl (need the Perl version 5.0 or later):

<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
The script asks you the name of your module, its major and minor version. A file '''mymodule.zip ''' will then be manufactured containing your module ready to be deployed.

*The person who receives your module must then place the file in the root directory of a Dolibarr installation and perform the command:

<source lang="bash">
tar -xvf mymodule.zip
</source>

*If you want your module to be public, you can submit it (the zip file) on Dolibarr marketplace website: {{LinkToPluginDownload}} (you must create an account first and be logged to use the link "Submit a module/product").
**If your module was built correctly, the file will be validated later.
**If quality is enough and license permits it, the code might be added inside main Dolibarr sources (except if you disagree for that).

=Enabling/activation condition of external module on DoliStore=

See [[Module_Dolistore_Validation_Rules|Validation Rules]]
[[Category:Development]]

Module development

2021-03-09T07:18:45Z

ALSOFT: /* Create a new PHP screen */

[[fr:Développement_module]]
[[es:Desarrollo_de_un_módulo]]
[[de:Modul_Entwicklung]]
[[zh:模块开发]]


[[Category:Core]]
{{TemplateDocDevEn}}

To create a new module/addon for Dolibarr, there is several steps. This tutorial will describe you each of them to build a module to extend Dolibarr features, like one or several of the following :

*Add new tables in database
*Add your own menu entries
*Add new screens to edit new tables
*Add or remove tabs on object view (invoice, product, order, event, ...)
*Add predefined exports for the internal export tool
*Add new information boxes in the home page
*Add new substitutions variables
*Define new permissions
*Execute code automatically triggered by a particular Dolibarr action
*Insert your code inside Dolibarr hooks positions
*Add your numbering module
*Add a new document template
*Add a new skin

etc...

Following chapters presents how to do all of this manually with an easy way.

=Module creation with the module builder=
From Dolibarr 9.0 it is possible to create the main pages of your module with the Module Builder. To activate it, go into the list of module and enable the module "Module Builder", then click on the "bug" image in the top right of screen.

=Example of Template External Module=
A good model to start development of external module can be found here : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

=Create your module=
==Create a Module descriptor for your Module (required)==
'''When it is required''': Required as soon as an addon is developed, whatever its goal is (except for adding a skin).

'''Since Dolibarr 9.0, you should use the ModuleBuilder module provided as a standard module to generate the module descriptor'''

===Create your module descriptor===
The first step is to create a file descriptor for the module.

*Create directory '''/htdocs/''mymodule''/core/modules'''. Then copy the file modMyModule.class.php from the directory dev/skeletons into this directory '''htdocs/''mymodule''/core/modules'''. Change the name of the file modMyModule.class.php to the name corresponding to the purpose of your module. Name of the file must start with initial 'mod' and end with .class.php (for example if you want to give the name 'NewName' to this file, then the name should be 'modNewName.class.php').

Next modify the contents of this file as follows:

*Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contain only alpha characters (again, if the name given to the file was 'NewName', then replace all "modMyModule" with "modNewName").
*Change the number in: $this->numero = 100000 by a number that designates your module id. To avoid conflicts with other modules, you can consult the page that lists already reserved id numbers: [[List of modules id|List of modules id]].
*Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).

Your file descriptor for your module is ready. See the next step to activate it.

===Test your descriptor===

Launch Dolibarr and go to page '''Setup->module'''?
If you set the property version in the module description you should see a new line with your new module and the possibility to activate it or not. If you set the property version to "develop" or "experiental", to see your module, you must first go into '''Setup-Others''' and set MAIN_FEATURES_LEVEL to 1 to see "experimental" modules or 2 to see "development" modules.

==Tree of path for new module files (required)==
This is how your files must be organized when building a new module (the zip file must also match this rule).
Note: Only the second line is mandatory.

{{TemplateModuleTreeSimple}}

==Create your SQL tables and the PHP DAO class (optional)==
'''When''': If your module needs to manage data of its own

===Create your .sql file===
If your module is designed to manage data of its own, which are not available in the standard version of Dolibarr, it is necessary to define SQL tables to store the data.

Scripts for creating tables and load data by your own module are saved into a subdirectory called "/mymodule/sql".

Then check into your descriptor file, into function '''init''' that the line

<source lang="php">$this->_load_tables('/mymodule/sql/');</source>

is not commented.

''Rules to follow:''

*Add the files about creating tables commands on the principle of a file '''llx_matable.sql''' per table, with a possibly file '''llx_matable.key.sql''' (see existing files in '''install/mysql/tables''' for examples).
*The recommended type and name for SQL fields are defined into page [[Language_and_development_rules#Table_and_fields_structures]].
*To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
*Don't use the double quote for strings (eg 'chaine' not "chaine") because the double quote have a specific meaning in PostGreSQL

Example of content of a file data.sql
<source lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</source>

Files must be operational for the database mysql. Rem: The files of other databases are not maintained. They will be read and converted on the fly by the driver of the other database.

===Test your .sql files===

Once the files ready, you can return to Dolibarr to disable the module, drop those tables in the database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.

===Generate the PHP DAO class===
Once you have created your tables into the database, move to the dev/skeletons directory and run the script

<source lang="bash">php build_class_from_table.php tablename modulename</source>
Note: If the command does not work, try to use php-cli php instead.

This will generate a file '''out.tablename.class.php''' that contains the class to manage table tablename.
In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table.
Remove just the "out" from the file name and put the file in a subdirectory of '''htdocs''' specific to your module (in htdocs/mymodule for example).

A file '''out.tablename_script.php''' has been generated and contains a sample code to use the class for each of the 4 CRUD methods.

'''Since Dolibarr 6.0, the file dev/skeletons/build_class_from_table.php is no more provided. To build a class from a table you should use the ModuleBuilder modules provided as a standard module.'''

==The tab management (optional)==

===Add or remove your own tabs on object sheets===
'''When''': To add a tab on an object (invoices, orders, proposals, member ...)

To do this go into the file descriptor of module previously created and edit the $this->tabs array:

<source lang="php">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</source>

The table should contain a list of strings, each string representing a new tab.
The format of the string consisting of 5 parts separated by ":"

*Part 1: The element type (object type) where the tab should appear is a value from the following:
{{TemplateModuleTabs}}

*Part 2: A code to identify tab to add (start with +) or to remove (start with -)
*Part 3: The title of the tab. This can be a hard read or better code translation in a file lang.
*Part 4: The name of the file "*.lang" which contains correspondence between the code translation and language to display. If this name is followed with @mymodule, Dolibarr will search translation file "*.lang" within the module, so htdocs/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mylangfile.lang
*Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
*Part 6: The URL of the page to display when you click on the tab. The __ID__ string will be replaced automatically by the Id of the element concerned.

To feed the contents of the tab with data from the database, see the next chapter.

In order to get the names 'tabname' of existing tabs, you have to check the names used in the function 'product_prepare_head' of the file 'core/lib/module.lib.php' corresponding to section '$head[$h][2]'.

===Show tabs navigation into your own pages===
'''When''': To show all standard tabs of an object (product, tiers, etc.) on your page.

You must follow these steps :

'''1. Include files you need into your file'''

For each object type, there are two files to include with line
<source lang="php">require_once($url_fichier) ;</source>

This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :

*Object thirdparty (thirdparty) :
**DOL_DOCUMENT_ROOT/societe/class/societe.class.php
**DOL_DOCUMENT_ROOT/core/lib/company.lib.php
*Object product (product) :
**DOL_DOCUMENT_ROOT/product/class/product.class.php
**DOL_DOCUMENT_ROOT/core/lib/product.lib.php
*Object invoice (invoice) :
**DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
**DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

...

'''2. Create and load the object to show into your tab'''

Create an instance of an object of the correct class and load object from the database by using the fetch method of an object in providing to this method the id you get from URL (ie : /mytab.php?id=1).

''Example :''
<source lang="php">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
</source>

'''3. Get a list of all tabs to show for your object type'''

Use function XXX_prepare_head($obj), where XXX is name of object. This will return an array with all definition of tab entries to show. The parameter to put into this method is the instance of an object you want tabs.

The resulting array has the following structure
<source lang="php">
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
</source>

''Example :''
<source lang="php">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
</source>

'''4. show tabs into your page'''

Use function dol_fiche_head() to show all tabs defined into array $head returned by XX_prepare_head().

<source lang="php">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
//$links // Tableau des onglets, appelé $head plus haut.
//$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module, ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
//$title // Title to show (shown into a special tab that you can't click)
//$notab
//$picto // Name of image to show into title. Possible values are:
// product
// service
// company
</source>

This function will show required tabs and open an html element ''< div class="" >'' that correspond to the area under the tabs. To close area of a tab, just use ''< /div >'' into your PHP page.

==Create or modify PHP screens (optional)==
'''When''': If the purpose of your module is to add features that require new or modified screens.

===Create a new PHP screen===
You must then create your PHP pages that will show/edit data from tables using the skeleton templates provided as an example in the directory '''modulebuilder/myobject_page.php''' (For the development of a script from the command line, see [[Script development]]).

To create a new user screen, create a subdirectory of '''htdocs''' (if not already done) for your module (in '''htdocs/mymodule''' for example) to store the pages you will create.

Copy, into that directory, the file '''myobject_page.phpp''' that will serve as a starting point for your page file.
Edit the file to have a correct relative path to the main.inc.php file.
<source lang="php">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root calculated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</source>
As you can see, there are several tries to load the main.inc.php (or master.inc.php). The goal is to succeed in the most cases as possible. The minimum is 2 lines: one to try to load the master/main.inc.php into the dolibarr root directory and another one to try to load the file to support the case when the module is deployed into the "custom" directory. But you can have more to deal more situation. The provided example should be able to load the file main/master.inc.php in nearly all situation/setups.

Note that you may add more "../" depending on the depth of the file relative to your module directory tree.

It's in the main.inc.php file that is loaded technical environment variables and permissions. The following variables are objects positioned in this file:

*$user Object that contains the characteristics of the user + his permissions.
*$conf Object that contains Dolibarr configuration.
*$db Object that contains an opened connection handler to the database.
*$langs Object that contains the user's language.

Then enter your code to display the page.

*To include a class or library dedicated to the module is done using a Dolibarr function (and not using directly include_once):

''Example :''
<source lang="php">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
</source>

*To include classes provided with Dolibarr, use the following syntax:

''Example :''
<source lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</source>

===Add some fields into existing forms===
You may want to provide a module that adds more fields into forms (input and view) of some elements.

A heavy solution (but not so bad) may be to replace all pages used to create element (this means to disable the "New element" menu entry and adding yours, and disable tab that shows element to replace with a tab that is your own full page (copied/pasted from original) to do same than original page but modified to add your fields and stored added data into your own table). Go to menu [[#Define your entries in the menu (optional)]] and [[#The tab management (optional)]] if this solution suits you (this solution is more powerful since you can change everything you want into the page).

We will describe here another solution, that works only to "add fields" at end of existing fields, using the element "category" as an example but you can convert this tutorial for invoice, proposal ...

*First thing is to add a table, owned by your module, to store the value of new fields. This table will have only one column called "rowid" (will contain the same value than field rowid of element table) + one column for each new field you want to add. Then create a class with CRUD (Create/Read/Update/Delete) methods for this new table. For this two tasks, go back to previous chapter [[#Create your SQL tables and the PHP DAO class]].
*Next step is to add a hook into your module to add the new fields into the form. See chapter [[Hooks_system#Implement_the_Hook]] for generic documentation to use hooks.

If you follow this tutorial, to be able to add fields into category forms, you must do:
{{ToComplete}}

===Replace parts of screen that are templated (version 3.3+)===
Some parts of Dolibarr screen are isolated into native PHP template files.
You can develop a module to overwrite such templates with yours.
{{ToComplete}}

===Add/replace part of fields supported by hooks===
See chapter [[Hooks_system#Implement_the_Hook]] to know how to use Dolibarr existing hooks to add/replace code at Dolibarr hooks place.

===Database access===
If you need to edit some data in the database inside your own table, use the PHP class generated before.

If you to make access to tables with no dedicated PHP class available, this is always possible (for example if you want to get a list of records with a particular join or filter). In this case, this is a code samples to follow:

To make an insert, update or delete:

<source lang="php">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</source>

To read:

<source lang="php">
$resql=$db->query("My select request");
if ($resql)
{
$num = $db->num_rows($resql);
$i = 0;
if ($num)
{
while ($i < $num)
{
$obj = $db->fetch_object($resql);
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}
</source>

===Define style of your pages===
To have the look of your own pages to match the Dolibarr theme, it is necessary to use the Dolibarr CSS styles.

You can use for example:

*class="'''liste_titre'''" on tags ''tr'' and ''td'' for the head row of a table.
*class="'''pair'''" or class="'''impair'''" on tags ''tr'' and ''td'' of other rows of a table.
*class="'''flat'''" on all input fields (''input, select, textarea''...).
*class="'''button'''" on HTML fields with type ''input type="submit"''.

===Use the Dolibarr date picker===
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
The string mykey will identify the date selector in the form. You must use different values if you use several date selectors in same page.
The string myform is the name of the FORM in which the selector is included (value found in the form name="myform" in HTML page).
This means a date selector must be included necessarily into an html FORM.

To get value after the POST of your form, the command is:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

==Add your own setup page (optional)==
'''When''': If your module needs parameters, which are to be provided by the user, for proper setting up of the module.

===Create your page to edit parameters===
If your module needs several parameters to be setup, you must create a page to edit options (these options will be saved in the [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that shows a form for possible options to update them into the above-mentioned table.
It is necessary to take an example from a page of the directory '''/admin''' that will show you the way to read/save your parameters.
Put this PHP page into the directory '''/admin''' of your module (e.g. mymodule/admin/mymodule_setuppage.php).

===Modify the descriptor file of your module===
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set the name of this PHP page.
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php");
</source>
If the page is in the directory '''mymodule/admin/''', then like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
</source>

===Test your page===
Go into page '''Home->Setup->Modules''', you should see a picture at the end of the line of your module to reach your setup page. Click on it, you should be able to view/edit parameters from your page.

==Define your entries in menu (optional)==
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

===Define your menu entries===
For this, you must define into the module descriptor, the array this->menu that declares all menus added by your module.
This array contains entries that will appear once your module is activated.
The example module descriptor file '''modMyModule.class.php''' contains an example to declare a top menu and also its left menu entries.

This is the example of code to declare your own menu entries in a module descriptor file:
<source lang="php">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'fk_mainmenu=xxx', // Use 'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is mainmenucode and yyy is a leftmenucode of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

To show the menu or not depending on a permission, modify property '''perms''' in the array. See chapter on permissions later to see how to add permissions.

===Test your menu entries===
Disable and re-enable your module under the Dolibarr module setup page, menus entries must appear (if property 'enabled' is declaration array is ok).

==Add your own permissions (optional)==
'''When''': If you want to add new permissions.

The way to define permissions that will manage your module is done inside the module descriptor created previously.
Modify line
<source lang="php">
$this->rights_class = 'mymodule'
</source>
with correct value for mymodule.

Then you must fill the array $this->rights with as many entries than different permissions you need to manage.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</source>

Into $this->rights[$r][0], put a permission id not already used (See into menu '''System info''' on a working installation of Dolibarr to know list of id already used by standard modules.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any newly created user.
Into $this->rights[$r][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''' Translation key should be "Permission10001=My permission Label").
Into $this->rights[$r][4] and $this->rights[$r][5], put an action and subaction string without spaces. You will be able to test if a user has the permission in your PHP source code with the sequence:

<source lang="php">
if ($user->rights->mymodule->action->subaction) ...
</source>

==Define your own box (optional)==
'''When''': If your module needs to provide one or several new boxes to show on home page.

===Define your box===
For this, modify the array $this->boxes into the module descriptor file.
All you have to do is to add 2 lines for each box file you will create into directory '''htdocs/mymodule/core/boxes'''

''Example:''
<source lang="php">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
</source>

Then create files '''htdocs/mymodule/core/boxes/mybox0.php''', '''htdocs/mymodule/core/boxes/mybox1.php'''... by copying an example from an existing box file (found into directory '''htdocs/core/boxes''').

===Test if your box is detected by Dolibarr===
Disable and enabled module.

Go into menu '''Home - Setup - Boxes'''.

Your boxes must appear in the list of boxes you can activate. Activate the box and go on the home page to see if the box is showing correctly.

==Define your own export (optional)==
'''When''': If your module provides new predefined database export profiles (for its own tables or for already existing tables of another module).

===Define export===
For this uncomment and modify arrays $this->export_xxx in your module descriptor file.

===Test your export===
Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled).
Choose it, you must see a list of all possible fields defined in the export arrays.
Choose on field and try to build an export file. If ok, try again with all fields.

==Define your CSS styles (optional)==
'''When''': If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommanded).

===Create and declare your style sheet===
Create a style sheet CSS named '''mymodule.css''' or '''mymodule.css.php''' and put it into directory '''htdocs/mymodule'''. You can have several CSS files per module.
Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file '''themes/mytheme/''themename''.css.php'''. Create your own CSS files only if you need absolutely to add not already existing styles.

Once your style sheets are ready, declare them into your module descriptor file by modifying the property '''$this->modules_parts'''.
Value to put here must be an array of relative URLs to your CSS files.
For example
<source lang="php">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));
</source>

===Test your style sheet===
Disable and enable your module.

Go on the home page (index.php). Show the HTML source of the page.

You should see into the HTML header, a line that declares your style sheet.

==Add your Javascript functions (optional)==
'''When''': If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)

If you need to use your own javascript functions inside your PHP pages, it is necessary to have your functions, defined into your javascript file '''htdocs/mymodule/js/mymodule.js''', included into the HTML HEAD section.
To ask Dolibarr that forge this header to include your own javascript file, you must just provide it to the llxHeader() function called by your page.

Example for page /htdocs/mymodule/mypage.php :
<source lang="php">
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</source>

==Run your own code on any Dolibarr event (optional)==
'''When''': If you want to execute your own code once a common Dolibarr event has occurred (example: I want to update a table in my module when an invoice is created into Dolibarr), you must create a '''triggers'''.

See also [[Interfaces_Dolibarr_toward_foreign_systems]]
and [[Interfaces_from_foreign_systems_toward_Dolibarr]]

==Insert your code inside Dolibarr hooks positions (optional)==
'''When''': When you want to add code or replace Dolibarr code into another situation than a business event (See the previous chapter for adding code during a business event).

See page [[Hooks_system]].

==Add your own numbering rules==
'''When''': When you need a new rule for generated ref of elements that are not covered by existing rules.

See page [[Create numbering module]].

==Add your document template (optional)==
'''When''': When you want to personalized your own generated PDF or ODT documents.

Note: To add this feature you don't need to create a module descriptor.

Documentation to add your own template is available on page [[Create_a_PDF_document_template]] or [[Create_an_ODT_document_template]].

==Add your skin (optional)==
'''When''': When you want to personalized your colors/fonts/images.

Note: To add this feature you don't need to create a module descriptor.

To add your own skin, read page [[Skins]].

=Some coding rules and predefined functions=
The coding rules to be followed are defined in the [[Developer documentation]], under section "General Information - Language and standards development".

A lot of predefined features for developers are also available and described into page [[Developer documentation]] under section "Technical components of Dolibarr".

=Create a package to distribute and install your module=
This process must be used to generate a package to submit it on the http://www.dolistore.com marketplace.
But you can use it to have a package easy to distribute on your own network.

*Go into the directory '''/build''' and copy the file '''makepack-dolibarrmodules.conf''' into '''makepack-mymodule.conf'''. Warning, this directory may not be provided in some packages of stable versions. If so, it can be retrieved from the snapshot available for download on the Dolibarr website in area "Development version" (taken in this case the whole build directory which is autonomous and independent directory).

Edit this file to add a list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

*Run the script via Perl (need the Perl version 5.0 or later):

<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
The script asks you the name of your module, its major and minor version. A file '''mymodule.zip ''' will then be manufactured containing your module ready to be deployed.

*The person who receives your module must then place the file in the root directory of a Dolibarr installation and perform the command:

<source lang="bash">
tar -xvf mymodule.zip
</source>

*If you want your module to be public, you can submit it (the zip file) on Dolibarr marketplace website: {{LinkToPluginDownload}} (you must create an account first and be logged to use the link "Submit a module/product").
**If your module was built correctly, the file will be validated later.
**If quality is enough and license permits it, the code might be added inside main Dolibarr sources (except if you disagree for that).

=Enabling/activation condition of external module on DoliStore=

See [[Module_Dolistore_Validation_Rules|Validation Rules]]
[[Category:Development]]

Module development

2021-03-09T07:18:20Z

ALSOFT: /* Create a new PHP screen */

[[fr:Développement_module]]
[[es:Desarrollo_de_un_módulo]]
[[de:Modul_Entwicklung]]
[[zh:模块开发]]


[[Category:Core]]
{{TemplateDocDevEn}}

To create a new module/addon for Dolibarr, there is several steps. This tutorial will describe you each of them to build a module to extend Dolibarr features, like one or several of the following :

*Add new tables in database
*Add your own menu entries
*Add new screens to edit new tables
*Add or remove tabs on object view (invoice, product, order, event, ...)
*Add predefined exports for the internal export tool
*Add new information boxes in the home page
*Add new substitutions variables
*Define new permissions
*Execute code automatically triggered by a particular Dolibarr action
*Insert your code inside Dolibarr hooks positions
*Add your numbering module
*Add a new document template
*Add a new skin

etc...

Following chapters presents how to do all of this manually with an easy way.

=Module creation with the module builder=
From Dolibarr 9.0 it is possible to create the main pages of your module with the Module Builder. To activate it, go into the list of module and enable the module "Module Builder", then click on the "bug" image in the top right of screen.

=Example of Template External Module=
A good model to start development of external module can be found here : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

=Create your module=
==Create a Module descriptor for your Module (required)==
'''When it is required''': Required as soon as an addon is developed, whatever its goal is (except for adding a skin).

'''Since Dolibarr 9.0, you should use the ModuleBuilder module provided as a standard module to generate the module descriptor'''

===Create your module descriptor===
The first step is to create a file descriptor for the module.

*Create directory '''/htdocs/''mymodule''/core/modules'''. Then copy the file modMyModule.class.php from the directory dev/skeletons into this directory '''htdocs/''mymodule''/core/modules'''. Change the name of the file modMyModule.class.php to the name corresponding to the purpose of your module. Name of the file must start with initial 'mod' and end with .class.php (for example if you want to give the name 'NewName' to this file, then the name should be 'modNewName.class.php').

Next modify the contents of this file as follows:

*Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contain only alpha characters (again, if the name given to the file was 'NewName', then replace all "modMyModule" with "modNewName").
*Change the number in: $this->numero = 100000 by a number that designates your module id. To avoid conflicts with other modules, you can consult the page that lists already reserved id numbers: [[List of modules id|List of modules id]].
*Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).

Your file descriptor for your module is ready. See the next step to activate it.

===Test your descriptor===

Launch Dolibarr and go to page '''Setup->module'''?
If you set the property version in the module description you should see a new line with your new module and the possibility to activate it or not. If you set the property version to "develop" or "experiental", to see your module, you must first go into '''Setup-Others''' and set MAIN_FEATURES_LEVEL to 1 to see "experimental" modules or 2 to see "development" modules.

==Tree of path for new module files (required)==
This is how your files must be organized when building a new module (the zip file must also match this rule).
Note: Only the second line is mandatory.

{{TemplateModuleTreeSimple}}

==Create your SQL tables and the PHP DAO class (optional)==
'''When''': If your module needs to manage data of its own

===Create your .sql file===
If your module is designed to manage data of its own, which are not available in the standard version of Dolibarr, it is necessary to define SQL tables to store the data.

Scripts for creating tables and load data by your own module are saved into a subdirectory called "/mymodule/sql".

Then check into your descriptor file, into function '''init''' that the line

<source lang="php">$this->_load_tables('/mymodule/sql/');</source>

is not commented.

''Rules to follow:''

*Add the files about creating tables commands on the principle of a file '''llx_matable.sql''' per table, with a possibly file '''llx_matable.key.sql''' (see existing files in '''install/mysql/tables''' for examples).
*The recommended type and name for SQL fields are defined into page [[Language_and_development_rules#Table_and_fields_structures]].
*To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
*Don't use the double quote for strings (eg 'chaine' not "chaine") because the double quote have a specific meaning in PostGreSQL

Example of content of a file data.sql
<source lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</source>

Files must be operational for the database mysql. Rem: The files of other databases are not maintained. They will be read and converted on the fly by the driver of the other database.

===Test your .sql files===

Once the files ready, you can return to Dolibarr to disable the module, drop those tables in the database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.

===Generate the PHP DAO class===
Once you have created your tables into the database, move to the dev/skeletons directory and run the script

<source lang="bash">php build_class_from_table.php tablename modulename</source>
Note: If the command does not work, try to use php-cli php instead.

This will generate a file '''out.tablename.class.php''' that contains the class to manage table tablename.
In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table.
Remove just the "out" from the file name and put the file in a subdirectory of '''htdocs''' specific to your module (in htdocs/mymodule for example).

A file '''out.tablename_script.php''' has been generated and contains a sample code to use the class for each of the 4 CRUD methods.

'''Since Dolibarr 6.0, the file dev/skeletons/build_class_from_table.php is no more provided. To build a class from a table you should use the ModuleBuilder modules provided as a standard module.'''

==The tab management (optional)==

===Add or remove your own tabs on object sheets===
'''When''': To add a tab on an object (invoices, orders, proposals, member ...)

To do this go into the file descriptor of module previously created and edit the $this->tabs array:

<source lang="php">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</source>

The table should contain a list of strings, each string representing a new tab.
The format of the string consisting of 5 parts separated by ":"

*Part 1: The element type (object type) where the tab should appear is a value from the following:
{{TemplateModuleTabs}}

*Part 2: A code to identify tab to add (start with +) or to remove (start with -)
*Part 3: The title of the tab. This can be a hard read or better code translation in a file lang.
*Part 4: The name of the file "*.lang" which contains correspondence between the code translation and language to display. If this name is followed with @mymodule, Dolibarr will search translation file "*.lang" within the module, so htdocs/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mylangfile.lang
*Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
*Part 6: The URL of the page to display when you click on the tab. The __ID__ string will be replaced automatically by the Id of the element concerned.

To feed the contents of the tab with data from the database, see the next chapter.

In order to get the names 'tabname' of existing tabs, you have to check the names used in the function 'product_prepare_head' of the file 'core/lib/module.lib.php' corresponding to section '$head[$h][2]'.

===Show tabs navigation into your own pages===
'''When''': To show all standard tabs of an object (product, tiers, etc.) on your page.

You must follow these steps :

'''1. Include files you need into your file'''

For each object type, there are two files to include with line
<source lang="php">require_once($url_fichier) ;</source>

This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :

*Object thirdparty (thirdparty) :
**DOL_DOCUMENT_ROOT/societe/class/societe.class.php
**DOL_DOCUMENT_ROOT/core/lib/company.lib.php
*Object product (product) :
**DOL_DOCUMENT_ROOT/product/class/product.class.php
**DOL_DOCUMENT_ROOT/core/lib/product.lib.php
*Object invoice (invoice) :
**DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
**DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

...

'''2. Create and load the object to show into your tab'''

Create an instance of an object of the correct class and load object from the database by using the fetch method of an object in providing to this method the id you get from URL (ie : /mytab.php?id=1).

''Example :''
<source lang="php">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
</source>

'''3. Get a list of all tabs to show for your object type'''

Use function XXX_prepare_head($obj), where XXX is name of object. This will return an array with all definition of tab entries to show. The parameter to put into this method is the instance of an object you want tabs.

The resulting array has the following structure
<source lang="php">
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
</source>

''Example :''
<source lang="php">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
</source>

'''4. show tabs into your page'''

Use function dol_fiche_head() to show all tabs defined into array $head returned by XX_prepare_head().

<source lang="php">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
//$links // Tableau des onglets, appelé $head plus haut.
//$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module, ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
//$title // Title to show (shown into a special tab that you can't click)
//$notab
//$picto // Name of image to show into title. Possible values are:
// product
// service
// company
</source>

This function will show required tabs and open an html element ''< div class="" >'' that correspond to the area under the tabs. To close area of a tab, just use ''< /div >'' into your PHP page.

==Create or modify PHP screens (optional)==
'''When''': If the purpose of your module is to add features that require new or modified screens.

===Create a new PHP screen===
You must then create your PHP pages that will show/edit data from tables using the skeleton templates provided as an example in the directory '''modulebuilder/myobject_page.php''' (For the development of a script from the command line, see [[Script development]]).

To create a new user screen, create a subdirectory of '''htdocs''' (if not already done) for your module (in '''htdocs/mymodule''' for example) to store the pages you will create.

Copy, into that directory, the file '''myobject_page.phpp''' that will serve as a starting point for your page file.
Edit the file to have a correct relative path to the main.inc.php file.
<source lang="php">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root calculated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</source>
As you can see, there is several tries to load the main.inc.php (or master.inc.php). The goal is to succeed in the most cases as possible. The minimum is 2 lines: one to try to load the master/main.inc.php into the dolibarr root directory and another one to try to load the file to support the case when the module is deployed into the "custom" directory. But you can have more to deal more situation. The provided example should be able to load the file main/master.inc.php in nearly all situation/setups.

Note that you may add more "../" depending on the depth of the file relative to your module directory tree.

It's in the main.inc.php file that is loaded technical environment variables and permissions. The following variables are objects positioned in this file:

*$user Object that contains the characteristics of the user + his permissions.
*$conf Object that contains Dolibarr configuration.
*$db Object that contains an opened connection handler to the database.
*$langs Object that contains the user's language.

Then enter your code to display the page.

*To include a class or library dedicated to the module is done using a Dolibarr function (and not using directly include_once):

''Example :''
<source lang="php">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
</source>

*To include classes provided with Dolibarr, use the following syntax:

''Example :''
<source lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</source>

===Add some fields into existing forms===
You may want to provide a module that adds more fields into forms (input and view) of some elements.

A heavy solution (but not so bad) may be to replace all pages used to create element (this means to disable the "New element" menu entry and adding yours, and disable tab that shows element to replace with a tab that is your own full page (copied/pasted from original) to do same than original page but modified to add your fields and stored added data into your own table). Go to menu [[#Define your entries in the menu (optional)]] and [[#The tab management (optional)]] if this solution suits you (this solution is more powerful since you can change everything you want into the page).

We will describe here another solution, that works only to "add fields" at end of existing fields, using the element "category" as an example but you can convert this tutorial for invoice, proposal ...

*First thing is to add a table, owned by your module, to store the value of new fields. This table will have only one column called "rowid" (will contain the same value than field rowid of element table) + one column for each new field you want to add. Then create a class with CRUD (Create/Read/Update/Delete) methods for this new table. For this two tasks, go back to previous chapter [[#Create your SQL tables and the PHP DAO class]].
*Next step is to add a hook into your module to add the new fields into the form. See chapter [[Hooks_system#Implement_the_Hook]] for generic documentation to use hooks.

If you follow this tutorial, to be able to add fields into category forms, you must do:
{{ToComplete}}

===Replace parts of screen that are templated (version 3.3+)===
Some parts of Dolibarr screen are isolated into native PHP template files.
You can develop a module to overwrite such templates with yours.
{{ToComplete}}

===Add/replace part of fields supported by hooks===
See chapter [[Hooks_system#Implement_the_Hook]] to know how to use Dolibarr existing hooks to add/replace code at Dolibarr hooks place.

===Database access===
If you need to edit some data in the database inside your own table, use the PHP class generated before.

If you to make access to tables with no dedicated PHP class available, this is always possible (for example if you want to get a list of records with a particular join or filter). In this case, this is a code samples to follow:

To make an insert, update or delete:

<source lang="php">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</source>

To read:

<source lang="php">
$resql=$db->query("My select request");
if ($resql)
{
$num = $db->num_rows($resql);
$i = 0;
if ($num)
{
while ($i < $num)
{
$obj = $db->fetch_object($resql);
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}
</source>

===Define style of your pages===
To have the look of your own pages to match the Dolibarr theme, it is necessary to use the Dolibarr CSS styles.

You can use for example:

*class="'''liste_titre'''" on tags ''tr'' and ''td'' for the head row of a table.
*class="'''pair'''" or class="'''impair'''" on tags ''tr'' and ''td'' of other rows of a table.
*class="'''flat'''" on all input fields (''input, select, textarea''...).
*class="'''button'''" on HTML fields with type ''input type="submit"''.

===Use the Dolibarr date picker===
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
The string mykey will identify the date selector in the form. You must use different values if you use several date selectors in same page.
The string myform is the name of the FORM in which the selector is included (value found in the form name="myform" in HTML page).
This means a date selector must be included necessarily into an html FORM.

To get value after the POST of your form, the command is:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

==Add your own setup page (optional)==
'''When''': If your module needs parameters, which are to be provided by the user, for proper setting up of the module.

===Create your page to edit parameters===
If your module needs several parameters to be setup, you must create a page to edit options (these options will be saved in the [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that shows a form for possible options to update them into the above-mentioned table.
It is necessary to take an example from a page of the directory '''/admin''' that will show you the way to read/save your parameters.
Put this PHP page into the directory '''/admin''' of your module (e.g. mymodule/admin/mymodule_setuppage.php).

===Modify the descriptor file of your module===
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set the name of this PHP page.
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php");
</source>
If the page is in the directory '''mymodule/admin/''', then like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
</source>

===Test your page===
Go into page '''Home->Setup->Modules''', you should see a picture at the end of the line of your module to reach your setup page. Click on it, you should be able to view/edit parameters from your page.

==Define your entries in menu (optional)==
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

===Define your menu entries===
For this, you must define into the module descriptor, the array this->menu that declares all menus added by your module.
This array contains entries that will appear once your module is activated.
The example module descriptor file '''modMyModule.class.php''' contains an example to declare a top menu and also its left menu entries.

This is the example of code to declare your own menu entries in a module descriptor file:
<source lang="php">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'fk_mainmenu=xxx', // Use 'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is mainmenucode and yyy is a leftmenucode of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

To show the menu or not depending on a permission, modify property '''perms''' in the array. See chapter on permissions later to see how to add permissions.

===Test your menu entries===
Disable and re-enable your module under the Dolibarr module setup page, menus entries must appear (if property 'enabled' is declaration array is ok).

==Add your own permissions (optional)==
'''When''': If you want to add new permissions.

The way to define permissions that will manage your module is done inside the module descriptor created previously.
Modify line
<source lang="php">
$this->rights_class = 'mymodule'
</source>
with correct value for mymodule.

Then you must fill the array $this->rights with as many entries than different permissions you need to manage.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</source>

Into $this->rights[$r][0], put a permission id not already used (See into menu '''System info''' on a working installation of Dolibarr to know list of id already used by standard modules.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any newly created user.
Into $this->rights[$r][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''' Translation key should be "Permission10001=My permission Label").
Into $this->rights[$r][4] and $this->rights[$r][5], put an action and subaction string without spaces. You will be able to test if a user has the permission in your PHP source code with the sequence:

<source lang="php">
if ($user->rights->mymodule->action->subaction) ...
</source>

==Define your own box (optional)==
'''When''': If your module needs to provide one or several new boxes to show on home page.

===Define your box===
For this, modify the array $this->boxes into the module descriptor file.
All you have to do is to add 2 lines for each box file you will create into directory '''htdocs/mymodule/core/boxes'''

''Example:''
<source lang="php">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
</source>

Then create files '''htdocs/mymodule/core/boxes/mybox0.php''', '''htdocs/mymodule/core/boxes/mybox1.php'''... by copying an example from an existing box file (found into directory '''htdocs/core/boxes''').

===Test if your box is detected by Dolibarr===
Disable and enabled module.

Go into menu '''Home - Setup - Boxes'''.

Your boxes must appear in the list of boxes you can activate. Activate the box and go on the home page to see if the box is showing correctly.

==Define your own export (optional)==
'''When''': If your module provides new predefined database export profiles (for its own tables or for already existing tables of another module).

===Define export===
For this uncomment and modify arrays $this->export_xxx in your module descriptor file.

===Test your export===
Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled).
Choose it, you must see a list of all possible fields defined in the export arrays.
Choose on field and try to build an export file. If ok, try again with all fields.

==Define your CSS styles (optional)==
'''When''': If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommanded).

===Create and declare your style sheet===
Create a style sheet CSS named '''mymodule.css''' or '''mymodule.css.php''' and put it into directory '''htdocs/mymodule'''. You can have several CSS files per module.
Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file '''themes/mytheme/''themename''.css.php'''. Create your own CSS files only if you need absolutely to add not already existing styles.

Once your style sheets are ready, declare them into your module descriptor file by modifying the property '''$this->modules_parts'''.
Value to put here must be an array of relative URLs to your CSS files.
For example
<source lang="php">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));
</source>

===Test your style sheet===
Disable and enable your module.

Go on the home page (index.php). Show the HTML source of the page.

You should see into the HTML header, a line that declares your style sheet.

==Add your Javascript functions (optional)==
'''When''': If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)

If you need to use your own javascript functions inside your PHP pages, it is necessary to have your functions, defined into your javascript file '''htdocs/mymodule/js/mymodule.js''', included into the HTML HEAD section.
To ask Dolibarr that forge this header to include your own javascript file, you must just provide it to the llxHeader() function called by your page.

Example for page /htdocs/mymodule/mypage.php :
<source lang="php">
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</source>

==Run your own code on any Dolibarr event (optional)==
'''When''': If you want to execute your own code once a common Dolibarr event has occurred (example: I want to update a table in my module when an invoice is created into Dolibarr), you must create a '''triggers'''.

See also [[Interfaces_Dolibarr_toward_foreign_systems]]
and [[Interfaces_from_foreign_systems_toward_Dolibarr]]

==Insert your code inside Dolibarr hooks positions (optional)==
'''When''': When you want to add code or replace Dolibarr code into another situation than a business event (See the previous chapter for adding code during a business event).

See page [[Hooks_system]].

==Add your own numbering rules==
'''When''': When you need a new rule for generated ref of elements that are not covered by existing rules.

See page [[Create numbering module]].

==Add your document template (optional)==
'''When''': When you want to personalized your own generated PDF or ODT documents.

Note: To add this feature you don't need to create a module descriptor.

Documentation to add your own template is available on page [[Create_a_PDF_document_template]] or [[Create_an_ODT_document_template]].

==Add your skin (optional)==
'''When''': When you want to personalized your colors/fonts/images.

Note: To add this feature you don't need to create a module descriptor.

To add your own skin, read page [[Skins]].

=Some coding rules and predefined functions=
The coding rules to be followed are defined in the [[Developer documentation]], under section "General Information - Language and standards development".

A lot of predefined features for developers are also available and described into page [[Developer documentation]] under section "Technical components of Dolibarr".

=Create a package to distribute and install your module=
This process must be used to generate a package to submit it on the http://www.dolistore.com marketplace.
But you can use it to have a package easy to distribute on your own network.

*Go into the directory '''/build''' and copy the file '''makepack-dolibarrmodules.conf''' into '''makepack-mymodule.conf'''. Warning, this directory may not be provided in some packages of stable versions. If so, it can be retrieved from the snapshot available for download on the Dolibarr website in area "Development version" (taken in this case the whole build directory which is autonomous and independent directory).

Edit this file to add a list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

*Run the script via Perl (need the Perl version 5.0 or later):

<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
The script asks you the name of your module, its major and minor version. A file '''mymodule.zip ''' will then be manufactured containing your module ready to be deployed.

*The person who receives your module must then place the file in the root directory of a Dolibarr installation and perform the command:

<source lang="bash">
tar -xvf mymodule.zip
</source>

*If you want your module to be public, you can submit it (the zip file) on Dolibarr marketplace website: {{LinkToPluginDownload}} (you must create an account first and be logged to use the link "Submit a module/product").
**If your module was built correctly, the file will be validated later.
**If quality is enough and license permits it, the code might be added inside main Dolibarr sources (except if you disagree for that).

=Enabling/activation condition of external module on DoliStore=

See [[Module_Dolistore_Validation_Rules|Validation Rules]]
[[Category:Development]]

Language and development rules

2021-03-08T11:29:16Z

ALSOFT: /* Index performance */

[[de:Sprachen_und_Programmierregeln]]
[[fr:Langages_et_normes]]
[[es:Lenguaje_y_Normas_de_Desarrollo]]
[[zh:语言和开发规则]]


{{TemplateDocDevEn}}

These are some rules on language, syntax and norm we use in the Dolibarr project:

=Versions=

*Dolibarr must work on:

#All OS (Windows, Linux, MACOS...)
#PHP {{PHPMinVersion}} (Must work with no need of complementary PHP module, except module to PHP module to access database).
#MySQL {{MySqlMinVersion}}

=Copyright Norms=

*All PHP files must start with a header that looks like

<syntaxhighlight lang="PHP">
<?php
/* Copyright (C) YYYY John Doe <email@email.com>
*
* Licence information
*/
...
</syntaxhighlight>
When you edit an existing file of project, you must add a Copyright line under others.

=PHP Norms=
==PHP==

*Dolibarr is written with PHP and supports all versions of PHP higher than {{PHPMinVersion}}. All files must end with extension .php

*Usage of PHP superglobals variables must use the dedicated operators $_COOKIES, $_SERVER, $_ENV but use the Dolibarr function GETPOST() to get the contents of $_GET or $_POST..

*Other operators ($HTTP_SERVER_GET, ...) are now deprecated in PHP, so they must not be used. Code must work if option '''register_long_arrays''' is set to off. Moreover, the code must work when PHP option '''register_globals''' is off (recommended by PHP). It must also work if the option '''register_globals''' is on (by default on a lot of installations).

*Do not use '''<s>PHP_SELF</s>'''. Use instead '''$_SERVER["PHP_SELF"]'''. Also, Dolibarr framework sanitizes content of $_SERVER["PHP_SELF"] variable (into main.inc.php file, before any business code).

*When several variables must be initialized with the same value, you must use individual declarations (separated by ;)

<syntaxhighlight lang="PHP">
$var1 = 1;
$var2 = 1;
$var3 = 1;
</sousyntaxhighlightrce>
instead of
<syntaxhighlight lang="PHP">
$var1 = $var2 = $var3 = 1;
</syntaxhighlight>
which is slower.

<br />

====Strings====

*Strings must be have variables outside of the quote.

<syntaxhighlight lang="PHP">
print "My text show my ".$variable." !\n";
</syntaxhighlight>

<br />

====Comments====

*Comments must use the C syntax, ie a double slash for a comment on one line and a slash-star to open a bloc for several lines

<syntaxhighlight lang="PHP">
/* Bloc of comment
*
* End of bloc
*/

$monobjet = new MonObjet($db);
$result=$monobjet->fetch($idobject);

for ($i = 1 , $i < 2 ; $i++) {
// comment on one line
print $i;
}

function myFunction($param1, $param2)
{
// code
}
</syntaxhighlight>

<br>

*Functions must return a value equal or higher than 0 if successful and strictly lower than 0 if error.

*No dead code (code never used) into Dolibarr core code (code used by external modules only must be included within the external modules).

*Use "include_once" for anything with functions or class definitions in it (like *.class.php and *.lib.php files), use "include" for template-style php with files containing common part of HTML and PHP code (like *.inc.php and *.tpl.php files).

*Coding style to use is the '''PSR-12''' (https://www.php-fig.org/psr/psr-12/). Only rules tagged "MUST" are currently required. So note however the exceptions:
**Length of line: PSR-12 mention we can't go up to 120 characters on same line, this is a soft limit. It is better to have long lines instead of long page with code content that is just data declaration and does not contain any logic. However, we introduced a hard limit of '''1000''' characters (having line larger than this may return errors on Continuous Integration tests).
**Tabs are allowed: The other exception is that we don't replace systematically the tabs with spaces. Using tabs is more convenient for most editors/developers. Also using spaces breaks some auto-format features (like Eclipse autoformat feature on some Eclipse version). For the moment, the best setup is "Keep spaces/tabs as it is", however, you can activate the option "Remove spaces at end of lines".
**We allow elements of an array on same line and we do not always add a new line at end of each element.
**Note 1: The following rule are very important to follow:
***Files must be saved with Unix format (LF) and not Windows (CR/LF). Unix format is compatible on all OS such as Unix like, Windows, Mac, but the Windows text file format may not work on some PHP under Unix.
***Smart tags PHP are not used. PHP code section must start with '''<?php'''
**Note 2: You can use the file '''dev/setup/codesniffer/ruleset.xml''' as rule file to control coding style with PHPCodeSniffer.
**Note 3: You can use the file '''dev/setup/eclipse/PSR-12 [built-in].xml''' as rule file to setup Eclipse syntax formater.
**Note 4: You may note that current code is not yet compliant with the PSR-12. The reason is that we must "now" follow the "MUST" rules of PSR-12, but it wasn't in the past. So feel free to change coding style to match new rules (keep in mind the 2 exceptions) if you find such cases.

==Classes and properties structures==

Some properties of classes are found in different classes. To avoid having different names, we will use the following PHP properties names:

{{TemplatePHPFields}}

=SQL rules=

==DDL file format==
Files containing definition of the database structure (DDL files) must be '''2 per table''':

*The first file defines the table and its fields. The file name contains the table name, e.g. like this: <tt>llx_''mytable''.sql</tt>

A comment will be added for each field to explain its usage.

*The second file defines all foreign keys, performance indexes or other constraints and the file name will be like: <tt>llx_''mytable''.key.sql</tt>

These files must be stored in the directory '''install/mysql/tables''' for all standard files or '''mymodule/tables''' for tables provided by an external module.

Example: '''file for creating the table llx_mytable will be llx_mytable.sql''':

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2013 Author <email@author.com>
--
-- This program is free software; you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation; either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program. If not, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

create table llx_mytable
(
rowid integer NOT NULL AUTO_INCREMENT PRIMARY KEY,
ref varchar(30) NOT NULL, -- object reference number
entity integer DEFAULT 1 NOT NULL, -- multi company id
ref_ext varchar(255),-- reference into an external system (not used by dolibarr)
field_one integer,
field_two integer NOT NULL,
fk_field integer,
field_date datetime,
datec timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,, -- creation datetime
tms timestamp, -- update time stamp
fk_user_author integer NOT NULL, -- Author, foreign key of llx_user
fk_user_mod integer NOT NULL, -- Last updater, foreign key of llx_user
import_key varchar(14) -- Use by import process
)type=innodb;
</syntaxhighlight>

Example: '''file for creating keys/indexes for the table llx_mytable will be llx_mytable.key.sql''':

<syntaxhighlight lang="sql">
-- ===========================================================================
-- Copyright (C) 2013 Author <email@author.com>
--
-- This program is free software; you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation; either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program. If not, see <http://www.gnu.org/licenses/>.
-- ===========================================================================

ALTER TABLE llx_mytable ADD UNIQUE uk_mytable_field (field_one, field_two);

ALTER TABLE llx_mytable ADD CONSTRAINT fk_mytable_fk_field FOREIGN KEY (fk_field) REFERENCES llx_matablepere (rowid);
</syntaxhighlight>

==Table and fields structures==

*Structure of tables.

When you create a new table, it is recommended to use the same conventions as other Dolibarr tables. This means the following fields:
- rowid INTEGER AUTO_INCREMENT PRIMARY KEY that is technical id of record
- entity INTEGER default 1 that is id for the multicompany feature
- date_creation datetime that is the creation date
- tms timestamp that will contain date of last modification (the database manages this field automatically, no need to manage it by the code, just create the field)
- date_valid datetime that is the validation date (if applicable)
- import_key varchar(32) that will contains the import code YYYYMMDDHHMMSS if you make mass import.
- status smallint to store a status
Eventually
- fk_user_creat or fk_user_author integer that is the id of user making creation
- fk_user_modif integer that is the id of user making change
- fk_user_valid integer that is the id of user validating record (if applicable)
- fk_soc integer that is the ID of the Third party (if applicable)

Note field:
- note_private text for private comment of the object
- note_pubic text for public comment of the object
or
- note text if there is no need to have private and public

*Type of fields:

Well, to be compatible with any accuracy required by any country on amounts, to be compatible with any database syntax and with the Dolibarr upgrade framework, we will use the following types for database fields:

- integer for a primary key, an integer or any of foreign key (bigint may also be accepted for very large tables)
- smallint for a small number (like for a status) or a boolean
- double(24,8) for any amount
- double(6,3) for any vat rate
- real for a quantity
- varchar for a string (also if length is 1, the type char is more and more deprecated)
- timestamp for a field date+time that is automatically updated
- datetime for a field date+time
- date for a field date
- text or medium text for large fields (no index allowed on such fields)

All business rules must be on same place, into PHP code, not into client, neither into database, that's why type enum is also not allowed.
Other type are not allowed for compatibility reasons.

*All tables has a prefix to avoid name conflicts with other projects. In current version this prefix is fixed ans can't be modified. Its value is <tt>llx_</tt>. In a future version this value should be modified during installation process.

==Primary keys==
The primary key of a table must be called <tt>rowid</tt>.

Some old tables does not use this rule and use a primary key called <tt>id</tt> (ie [[Table llx_c_actioncomm]]), but the reason is history and this should not happen anymore.

==Foreign keys==
Name of a foreign key must start with the prefix <tt>fk_</tt> followed by the table name (i.e. name of the referencing table) (this is required to avoid duplicate names in project that are not allowed even if in different tables by some DBMS like Postgresql) then the field name (i.e. name of the referencing field) (this is to allow to have several foreign keys in same table).

Example:
''fk_facture_fourn_fk_soc'' is a foreign key in the table llx_facture_fourn for the field fk_soc in this table (that references the rowid field in another table)

Note: If you develop your own external module, it must have no foreign keys that point to Dolibarr standard tables. This will break standard dolibarr upgrades, repair, backup and restore tools and may also break standard features.

==Alternative keys==
Sometimes, we need another unique keys than primary key. We can add in this case an alternate unique key. When we need this, we can create an alternate unique key. Such an index is called by a name that start by prefix <tt>uk_</tt> followed by an underscore, then the the table name (this is required to avoid duplicate names of unique keys that may create problems for some DBMS like Postgresql) and then another string to define the key (this is to allow to have several unique keys on same table).

Example:
''uk_societe_code_client'' is a unique key on table llx_societe on field code_client.

==Index performance==
Some fields are often used as search or order criteria, or for joins. In such case, we need to set a performance index on field to increase performances. Such indexes are named with a prefix <tt>idx_</tt> then the table name and then the field name.

Example:
''idx_societe_user_create'' is a performance index on table llx_societe for field user_create

==SQL Coding rules==

*Alias usage/Fields naming

When doing select, we can use alias to simplify writing/reading of requests:
<syntaxhighlight lang="sql">
select chp1, chpxxx2 as chp2 from table2 as t1, table2 as t2 where t1.chpx = t2.chpy
</syntaxhighlight>
However, we must not used alias for update request as they are not compatible with Mysql 3.1.

*Using SELECT * is forbidden ! When using SELECT you must define complete list of fields to get. This avoids confusion. And above all, this make reengeering of code easier and make impact analysis of change on a field possible. Example:

<syntaxhighlight lang="sql">
SELECT field_a, field_b, field_c FROM table_1 WHERE field_d = '$id'
</syntaxhighlight>

*Into SQL requests, you must quote fields except the fields that contain amounts which must be stored as double or real type. Quotes on numbers may result in saving as a different value. For example 412.62 in an insert will be saved as value 412.61999512 into database (due to implicit conversion string to numeric) if the target field has type double(24,8). Only PHP see value 412.61999512. Other tools will see 412.62 giving a sense that there is no problem. But it's PHP that has the good vision. There is really a wrong value into database. By removing quotes on numbers, no problem occurs.

Example:
<syntaxhighlight lang="sql">
Good: INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', 412.62)
Bad: INSERT INTO table_1 (field_txt, field_num) VALUES ('txt', '412.62')
</syntaxhighlight>

Note, problem of float numbers is same problem on all langauges and not only when inserting data into database. It occurs also with any language when you work on "real" numbers, so numbers must be, as soon as they are affected, cleaned with function price2num with second parameter defined to :
'MU' (for unit prices), 'MT' (for total prices) or 'MS' (otherwise) depending on usage of number. (see function documentation)

*Functions NOW, SYSDATE or DATEDIFF are forbidden inside SQL requests. If you must use the current date into a field, value must come from the PHP and not from the database engine. This is for better portability of code and correct management of TimeZone.

For example, don't do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = NOW()";
</syntaxhighlight>
but do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield = '".$this->db->idate(dol_now())."'";
</syntaxhighlight>

For example, don't do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where DATEDIFF(table.datefield, NOW()) > 7";
</syntaxhighlight>
but do:
<syntaxhighlight lang="PHP">
$sql="SELECT rowid FROM table where datefield < '".$this->db->idate(dol_now() - (7 * 24 * 3600))."'";
</syntaxhighlight>

An other advantage of this rule, is that request benefits of index because we are making a compare of a field with a fixed value. When using datediff, you make an operation on field before comparison, this means database can't use the index on field, resulting on very bad performance compared to solution without the datediff.

*Use $db->ifsql for SQL IF

Do not include the IF into your forged SQL request. But use instead $db->ifsql() method to you will make a SQL IF that is compatible with all SQL databases.

==Using Database triggers==
Using Database triggers is not allowed into the code of Dolibarr, so you should have no troubles with Database triggers.
Database triggers are not portable. Compatibility may be broken when upgrading your version of your database, database triggers are often not included into backup tools, database triggers need permissions that you may not have (and should not have) on a common secured database, database triggers means also that you include some "business rules" of your application into the database where most other rules are managed by the code itself creating conflict or code that can't be debugged with a step by step debugger, ...
There is tons of reason why we do not recommand to use database triggers in your own development.
Using Database triggers can save you time when you make development but is a very bad practice, so is forbidden as it is not compatible with the high level of quality of code expected by Dolibarr team. External modules that uses Database triggers may also be refused on the market place since it won't work for more than 50% of users.

==MySQL-MariaDB specificity==

*Tables must be declared with format InnoDB.

This format supports foreign keys and their restrictions, and transactions integrity is also supported. This guarantees that Dolibarr events keep all data with correct values between tables even when transaction modify different tables.

*Dolibarr MUST work even if MySQL option '''strict''' is active.

To activate it (required when developing on Dolibarr), add the following line into the config file of your MySQL server (my.cnf or my.ini)
{{MySqlStrictMode}}

==PostgreSQL specificities==
Only MySQL files must be maintained.
Those files are converted "on the fly" by the database Dolibarr driver.

There is an exception for the SQL "UPDATE FROM":

MySQL Syntax:
<syntaxhighlight lang="sql">
UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid;
</syntaxhighlight>

PgSQL Syntax:
<syntaxhighlight lang="sql">
UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid;
</syntaxhighlight>

There is no native SQL requests "UPDATE FROM" in all Dolibarr core. But if you use one in your own code of your module, you should do :
<syntaxhighlight lang="PHP">
if ($this->db->type=='pgsql') {
$sql="UPDATE table_taget as target SET fieldtarget=source.fieldsource
FROM table_source as source WHERE source.rowid=target.rowid";
} else {
$sql= "UPDATE table_taget as target, table_source as source SET fieldtarget=source.fieldsource
WHERE source.rowid=target.rowid";
}
</syntaxhighlight>

=HTML norms=
==Syntax rules==

*HTML used must be HTML compliant and not XHTML. All attributes of HTML tags must be in lower case and quoted with ".

*Links href must be absolute and use the function dol_buildpath() to get absolute path from a relative path and img tag must be build using function img_picto().

For example:
<syntaxhighlight lang="PHP">
print '<a href="'.dol_buildpath('/mydir/mypage.php').'">'.img_picto('Texte alt','namepictopng','').'</a>';
</syntaxhighlight>

*HTML tables must have columns with no forced width, except for columns that contains data we know the length. For example, a column with a picto only can be forced to with="20px".

Otherwise, we must avoid forcing the column width. Reason is that, in most cases, the browser make a better works to define column width automatically than forced values, and it works whatever is the resolution.

*Javascript/ajax code and call to javascript files into php pages must be avoided. However, if you need to include javascript code, you must add a condition on "$conf->use_javascript_ajax"

<syntaxhighlight lang="PHP">
if ($conf->use_javascript_ajax) {
... // php code generating javascript here
}
</syntaxhighlight>

*Popup windows must not be used, except for tooltips (and must have a condition as explained before).

*External scripts must be written in Perl if they can't be written in PHP. Usage of another language is not forbidden but must be argued before in the development mailing-list.

==External templating framework ?==
There is ton of frameworks to provide a templating language of an HTML page. The best and faster is just called "PHP", and because Dolibarr already depends on PHP, there is no need to introduce a dependency on a third language.

All templating frameworks are just preprocessor, BEFORE PHP. It can't be faster than PHP alone. When we say "speed is increased because templating framework use a cache", you must read in fact "the overtime spent by the framework is reduced by cache, not the speed of processing PHP file". We should say "any templating framework has an overload over PHP, the cache of the templating framework just reduces the slowing effect of using this framework", but not "the speed is increased, it is always decreased compared to pure PHP".

Above all, having a templating system is completely possible by doing a "'''.tpl.php'''" file that dos not contains any logic code, but only HTML and "echo". We get same result (but faster and easier to develop because it does not need to do all the setXXX before calling each template). All variables (known by code that include the template) are automaticaly known into a PHP template page. No risk to forget a set, and a lot of line of codes reduced, a lot of time and development errors are also saved.

Also, keeping a 100% isolation between code and HTML output is interesting in only 1 situation: When teams building design is complety different than team building logic code, AND if you build not too sophisticated pages, AND with no need of too many Ajax features (this need to know how code works).
And this situation is surely not the Dolibarr future (team will often be same, Ajax will be more and more present, event if I hope not too much, and screens are more and more dependent of dynamic or contextual events, difficult to have this with one simple template without transforming the template into a page with high level of code).

There is a ton of other reasons to not use an external templating system and all arguments to use them are also the best argument to use PHP as our templating system.

=Dolibarr norms and code skeleton=

==Skeleton code==
To standardize the code, and to speed up the development of new components in Dolibarr, you'll find skeletons of files fully prepared in the directory '''htdocs/modulebuilder/templates/'''.

For example:

*1 file that serves as an example of the module description: '''myModule.class.php'''
*1 file that serves as an example of code for creating a new class: '''skeleton_class.class.php'''
*1 file that serves as an example of code for creating a new page: '''skeleton_page.php'''
*1 file that serves as an example of code for creating a script for executing command lines: '''skeleton_script.php'''

...

Use it as an example.
Note that the skeletons are also used by the PHP Code generator ([[Module ModuleBuilder]]), which is described in the development chapter of Dolibarr modules, to speed up your development.

==Dates and Timezones==
Dolibarr is an application that is multi-user and multi-location. It's therefore necessary to store dates in the right format. To avoid problems with conversions, the following rules should be applied:

*A date into memory must always be stored with Timestamp GMT format.
*A date stored into database, is the GMT Timestamp of date submitted into the request usng the <b>PHP server</b> timezone. This does not apply to date update automatically by database (fields '''tms''' into database).

For exemple le 1st january 1970, 3 hour at Paris (TZ=+1) = 2 hour at Greenwitch (TZ=0) will be stored into memory with value 7200 and will be submitted into a SQL request to database with the string '19700101030000' (PHP convert into its TZ hour and database will unconvert it using its timezone too that is same than PHP).

All select methods should translate date fields, that are with format TZ of database ('19700101030000'), into a timestamp field by calling the method db->jdate. This is to store into memory a GTM Timestamp date. All insert methods must convert, during generation of SQL request, the memory date into the string by using db->idate (you may find examples into skeleton).

*Dates that are updated automatically (field '''tms''' into database) contains a GMT Timestamp GMT of date when change is done. The select will also use the db->jdate (that use PHP server TZ) to convert read data into a GMT Timestamp into memory. So if timezone of database differs from timezone of PHP server (one of them is not correctly set), you may experience differences between creation date and update date.

*Manipulation date with PHP must be done using the Dolibarr date functions: '''dol_now(), dol_mktime(), dol_stringtotime(), dol_getdate(), dol_time_plus_duree()'''. You may also find other functions available into file '''date.lib.php'''.

==UTF8/ISO encoding==
Dolibarr stores data in the following way:

*In database, data is stored in UTF8 or ISO. It depends on the database's pagecode therefore these options are set at creation time. In any case, Dolibarr's database driver (in lib/database) deals with it to convert from/to UTF8 at insertion and readout.
*Memory data is stored in UTF8 (PHP object instances).
*Web pages are returned and rendered into UTF8

==Float numbers, amount and calculation==
With PHP, like other languages (Java for exemple), non integer data (float, real, double) are not reliable for calculation.
Try to make for example
<syntaxhighlight lang="PHP">
print 239.2 - 229.3 - 9.9;
</syntaxhighlight>
You wont get zero but a very small decimal number. If you get zero her, you should be able to find other examples that don't work.
Problem of float is general, so a variable that is a result of a calculation using decimal numbers must ALWAYS be cleaned using the function '''price2num()''' with the econd parameter to: 'MU', 'MT' or 'MS' depending on need (see description of function).
<syntaxhighlight lang="PHP">
print price2num(239.2 - 229.3 - 9.9, 'MT');
</syntaxhighlight>
If data manipulated is not an amount, then using MU, MT, MS has no sense, and you must use the function '''round()'''.

==Creation of tables==
Do not create tables, on the fly, during execution by a standard user, we mean, during current usage of software.
If you create a module that uses its own table, not available in the default Dolibarr code, then take a look at tutorial [[Module development]]. It explains how to provide new tables with your module, so that, the tables will be created during module activation and not during module usage.

==Comparing version==
If your code need to make different things depending on Dolibarr version, you can use the following tip to detect and compare versions
<syntaxhighlight lang="PHP">
$version=preg_split('/[\.-]/',DOL_VERSION);
if (versioncompare($version,array(5,0,-4)) >= 0) { //mycode for 5.0 only; } // For dolibarr 5.0.* (the -4 means we include also alpha, beta, rc and rcX)
</syntaxhighlight>

But this solution need to include the function versioncompare. An alternative solution to test version is to do:
<syntaxhighlight lang="PHP">
if ((float) DOL_VERSION >= 5.0) { //mycode for 5.0 only; } // For dolibarr 5.0.*
</syntaxhighlight>

==Logs==
Add logs to your code using function
<syntaxhighlight lang="PHP">
dol_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_WARNING|LOG_ERR);
</syntaxhighlight>

==Working directory==
If you need to create a working directory, into your code, refer to it with
'''DOL_DATA_ROOT.'/mymodule''''

The directory can be created into your code by the following function:
<syntaxhighlight lang="PHP">
$mymoduledir=DOL_DATA_ROOT.'/mymodule';
dol_mkdir($mymoduledir);
</syntaxhighlight>

If you need a directory to store temporary data, this directory must be '''DOL_DATA_ROOT.'/mymodule/temp''''

=Design patterns and Object programming=

==Creation design patterns (GoF)==
Design patterns defined by the Gang Of Four (see wikipédia on [[w:Design patterns|Design patterns]]).
No usage of such patterns is required. We found some objects next to Singletons or Factory but not completely compliant with syntax, this is to be compatible with PHP 4 that is not a pure object language.

==Structure design patterns (GoF)==
Design patterns defined by the Gang Of Four (see wikipédia on [[w:Design patterns|Design patterns]]).
No usage of such patterns is required.

==Behavior design patterns (GoF)==
Design patterns defined by the Gang Of Four (see wikipédia on [[w:Design patterns|Design patterns]]).
No usage of such patterns is required.

==Design patterns of enterprise (Martin Fowler)==

===Patterns of code organization===
[[w:Martin Fowler|Martin Fowler]] has identified 3 ways to organize code:

*The '''Transaction Script''' (The source code is linear for each user action).

This is the old school used by all procedural languages.
Inconvenient: Redundancy of code. Need to know the physical model of data to develop.

*The '''Domain Model'''

This notion is available with object languages. It is business process (to identify before) that are used for objects classes.
Inconvenient: Model very complex to maintain.

*The '''Table Module'''

This is a mix between 2 previous where we have only one unique class for each table of database.

-> As shown in code skeletons (see previous chapter), Dolibarr uses concept of '''Table Module'''.

===Communication between business logic - data (ORM)===

There are 3 ways to make links:

*The '''Table And Row Data Gateway'''

This is the most simple. You have one class per table and each class is a link to the table with CRUD methods (Ceate, Read, Update, Delete). A class instance is a record in the table. The class contains only code to reach lines and fields of table.

Example: This mode is used by some ORM Frameworks, like '''iBatis''' (http://ibatis.apache.org/).

*The '''Active Record'''

Same as previous, but we are allowed to add some business functions into the class, if such functions are dedicated to the table or recording into this table.

Example: This mode is used for Dolibarr development and most PHP software that includes their own framework and best practices.

*The '''Data Mapper'''

Classes represent entities of the problem and not the data. So you have to double, triple ... these classes with Mapper classes to access the data.
More "purist" on paper (closer of business), this method also has the disadvantage of being more complex in practice.

Example: This is the choice if you use the ORM Framework '''Propel''' (http://propel.phpdb.org/trac/). We find this model in heavier applications, based on this ORM among others.

-> For Dolibarr development, it is recommended to use the connection mode '''Active Record''', which offers the advantages of a model close to the business without having the complexity, without obfuscating technical architecture. It is by this way that the development, understanding of code and technical maintenance and / or business behaviour seems the more productive (this is however an ongoing debate between the purists and the pragmatists, debate in which nobody can really be right, because it depends on the objectives).
[[Category:Development]]

==Design pattern for Graphic interfaces (MVC)==
There are several design patterns for user interfaces (MVC, MVP, MVVM).
Many confuse this design pattern with that of using a template framework. It's unrelated. A template framework (see previous point) is only linked to the "V" part of these models.

-> Dolibarr uses the '''MVC''' Design Pattern. Part M is materialized by a DAO class containing the CRUD (Create-Read-Update-Delete) methods for accessing the table.
Many frameworks have chosen to put the C code part (Controller) and the V code part (View) in different files, or even separate directories. The maintenance seems easier on paper, in practice, you have to juggle constantly between a ton of files when your project become larger. In Dolibarr, the separation is made by a simple comment section. The part of code C (Controller) is therefore the code that follow the tag
<pre>
/*
* Actions
* /
</pre>
It is followed by the part of code V (Vue), well separated from the C by the tag
<pre>
/*
* View
* /
</pre>

This mode of separation has had a neutral effect on new developments but has made it possible to reduce the time required for maintenance and fixing bugs so significantly that it is not envisaged to switch to another type of separation (yes the findings made in real life are not always those expected by school theory). The important thing remains that there is always a separation between C and V, no matter how this separation is materialized, as long as it is (Reminder: Do not confuse the notion of separation of C and V with the notion of separation of the code to feed the data of a View and of the code to format the View, this a principle of separation relating to the Design Pattern of Vue, see next point).

==Design pattern for Views - Presentation==
There are frameworks that specialize in Vue Design Pattern, the part of formatting the screen seen by the user.
Old versions of Dolibarr used Smarty. This framework is an overlay to an already very powerful screen formatting framework called ... PHP. The benefits being much lower than the disadvantages, it has been abandoned in favor of PHP templates (.tpl.php file) which remain the simplest, the most universal, the most scalable and the most efficient, of the presentation frameworks.

Its only flaw is that it cannot guarantee 100% the deviations of a developer who would integrate into the View, a logic unrelated to the presentation (therefore other than code intended for generation, formatting, HTML output , test or loop logic). This point is however controlled by the validation mechanism of the project managers' code.

Here again, it is the experience and the observation of a better productivity performance that has motivated the abandonment of the external Presentation frameworks in favor of the PHP framework.

List of modules id

2021-03-07T06:06:02Z

ALSOFT: /* ID 100000 - 499999 */

[[Category:Core]]
{{TemplateDocDevEn}}
{{TemplateDocDevEs}}
{{TemplateDocDevFr}}

{{Flag en}}
This page list all reserved modules numbers / ID. If you build or want to build your own modules (like this [[:Category:Complementary_modules|complementary module]]), you should take an ID range here. Please pick range into existing holes first.

{{Flag fr}}
Cette page recense tous les numéros / ID réservés de modules. Si vous avez réalisé ou voulez réaliser vos propres modules (comme les [[:Category:Modules complémentaires|modules complémentaires suivant]]), vous devriez prendre une plage d'ID ici. Merci de prendre dans les trous existant en priorité !

{{Flag sp}}
Esta página contiene un listado de todos los id reservados para los módulos. Si ha creado o quiere realizar sus propios módulos, (como estos [[:Category:Módulos_complementarios|módulos complementarios]]), deberá reservarse un rango de ID aquí.

=ID 0 - 99999=
{{Flag en}}
Reserved for Dolibarr's internal modules.

{{Flag fr}}
Réservé aux modules internes de Dolibarr.

{{Flag sp}}
Reservado a los módulos internos de Dolibarr.

=ID 100000 - 499999=
{{Flag en}}
Reserved area for editors in need for an ID range. You can edit this page to add your own range (take a range of 50 numbers only the first time, 1000 max per company)

{{Flag fr}}Zone réservée aux éditeurs qui ont besoin d'une plage d'ID spécifiques. Vous pouvez modifier cette page pour réserver votre plage (limitée à 50 valeurs la première fois, 1000 maximum par société)

{{Flag sp}}
Área reservada para los partners que necesiten un rango de ID. Puede modificar esta página para reservar su rango (limitado a 50 valores por editor)

[[File:Warning.png]] If you reserve more than 50, we may automatically change your reservation range without information and you may experience conflicts with other modules in a future, so please follow the rules !

*ID 100000 - 100999: OpenThink (http://www.openthink.be)
*ID 101000 - 101999: NLTechno (https://www.nltechno.com)
*ID 102000 - 102999: Tiaris (http://www.tiaris.fr)
*ID 103000 - 103999: Open-concept.pro (http://www.open-concept.pro)
*ID 104000 - 104999: ATM Consulting (http://www.atm-consulting.fr)
*ID 105000 - 105999: GPC.solutions
*ID 106000 - 106999: PHPASSO
*ID 107000 - 107999: TecLib (http://www.teclib.com) / Auguria (http://www.auguria.net)
*ID 108000 - 108999: ETHICWEB
*ID 109000 - 109999: Oas services ([http://www.oas-services.fr https://www.oas-services.fr])
*ID 110000 - 110999: Librethic (https://librethic.io)
*ID 111000 - 111999: Asset IT (www.assetit.ch)
*ID 112000 - 112999: Aarboard AG (www.aarboard.ch)
*ID 113000 - 113999: Asilib - Alexandre Spangaro
*ID 114000 - 114999: Iceleaf OÜ
*ID 115000 - 115999: 2A2C Conseil - Cyril ZEKSER
*ID 116000 - 116999: Wolftec GmbH
*ID 117000 - 117999: Oscim (http://www.oscim.fr)
*ID 118000 - 118999: Oarces Web (dev.oarces.com)
*ID 119000 - 119999: Manuel Berrocal - Absolacom
*ID 120000 - 120999: Régis Houssin (http://www.inodbox.com)
*ID 121000 - 121999: Oscss - Shop
*ID 122000 - 122999: MrSof - la Nation du Web
*ID 123000 - 123999: Bruno Généré (webiseasy.org)
*ID 124000 - 124999: backbone internet service (www.backbone.co.at)
*ID 125000 - 125999: ProgSI (www.progsi.ma)
*ID 126000 - 126999: Catalanet
*ID 127000 - 127999: Virgilio Filho pt-BR Brasil (@dolibarr.br)
*ID 128000 - 128999: Nicolas Frappé France (www.sospc.info)
*ID 129000 - 129999: Adeo-Informatique
*ID 130000 - 130999: Technicks ICT (http://www.technicks.eu)
*ID 131000 - 131999: Joan Louis (itaca.fr)
*ID 132000 - 132999: Jean-Marie Arsac (https://azimut.fr)
*ID 133000 - 133999: Oriel Systems Ltd, UK. (www.orielsystems.com)
*ID 134000 - 134999: ALSOFT PVT. LTD. (https://www.alsoft.org)
*ID 135000 - 135999: Net-Logic (http://netlogic.fr)
*ID 140000 - 140999: Altairis (http://altairis.fr)
*ID 141000 - 141050: Projet2Team (https://www.projet2team.fr)
*ID 141051 - 141099: Elistair (http://elistair.com)
*ID 141100 - 141149: Blue Networks Technologies (https://www.blnt.fr)
*ID 141150 - 141199: Florian DUFOURG - France
*ID 142000 - 142049: ITANéA (https://www.itanea.fr)
*ID 142050 - 142099: ERP Consulting NZ ([https://www.erpconsulting.co.nz www.erpconsulting.co.nz])
*ID 150000 - 150999: Jeffinfo
*ID 160000 - 160999: Charles-François BENKE (http://www.patas-monkey.com)
*ID 161000 - 161999: Abbes Bahfir (http://dolipar.org)
*ID 162000 - 162999: Jacques Rébiscoul
*ID 163000 - 163999: Open-DSI (https://www.open-dsi.fr)
*ID 164000 - 164999: Pixelada S. Coop. And. (https://pixelada.org)
*ID 165000 - 165049: DovConnect
*ID 165050 - 165099: Mind Operated Systems (https://www.mosystems.biz)
*ID 165100 - 165150: SD-Formation (https://sdformation.fr)
*ID 170000 - 170999: TRIDENT CONSULTING LTD (www.tridentdxb.com)
*ID 171000 - 171999: LVSInformatique (www.lvsinformatique.com)
*ID 172000 - 172299: Ray Soft-Systems (https://www.ray-soft-systems.com)
*ID 172300 - 172349: Günter Lukas Consulting (https://gl.co.at)
*ID 172350 - 172399: MB Informatique (https://www.mb-informatique.fr)
*ID 172400 - 172449: Professional Structures Limited (https://pstructures.com)
*ID 172450 - 172699: IT-BS (https://www.it-bs.fr)
*ID 172700 - 172749: Indelog (https://www.indelog.fr)
*ID 172750 - 172799: NS-INFO90 (https://www.ns-info90.fr)
*ID 180000 - 180999: Triangle Ingénierie
*ID 181000 - 181999: TI Sin Problemas (https://www.tisinproblemas.com)
*ID 182000 - 182049: Chipserv Pawel Wlizlo (https://www.testware.it)
*ID 183000 - 183999: BB2A Anthony Berton (https://www.bb2a.fr)
*ID 190000 - 190999: Diciannove (http://19.coop)
*ID 191000 - 191999: Elonet (https://elonet.fr)
*ID 199000 - 199999: RFMS
*ID 200000 - 200999: Noxiome
*ID 201000 - 201999: Sasa Ostrouska (saxa)
*ID 202000 - 202999: Z-Application
*ID 203000 - 203099: Elidee - elidee.com
*ID 203100 - 203999: Garcia MICHEL (soamichel.fr)
*ID 204000 - 204999: Ari Elbaz elarifr - accedinfo.com
*ID 205000 - 205999: Kreiz IT
*ID 206000 - 206999: GBINFO (www.gbinfo.fr)
*ID 207000 - 207099: MacroProg (https://www.macroprog.com)
*ID 207100 - 207149: Reactiva Software
*ID 207150 - 207199: Ndejje University Water Research and Development Centre ([https://github.com/NDUWRDC/LIMS/])
*ID 207200 - 207299: Massaoud Bouzenad ([https://www.dzprod.net dzprod.net])
*ID 207300 - 207349: Ksar
*ID 207350 - 207399: Easylinux (www.easylinux.fr)
*ID 222000 - 222999: dolibit (https://www.dolibit.de)
*ID 230000 - 230049: Unareil (https://www.unareil.eu)
*ID 230050 - 230099: Lyra Network (https://www.lyra.com/)
*ID 230100 - 230149: Gheorghe Iftimi - CTW - RO
*ID 230150 - 230199: MEMA Machinery & Tools (https://www.mema.be)
*ID 230200 - 230249: Teleassist
*ID 230250 - 230299: Nh Developer
*ID 230300 - 230499: Chickenforce/code-chicken, IT Services Hahn (https://github.com/code-chicken [http://itservices-hahn.de/ https://itservices-hahn.de])
*ID 230500 - 230549: Hidup Consulting (https://consulting.hidup.io)
*ID 230550 - 230599 : CMR Conseil (https://www.weblockup.fr)
*ID 230600 - 230649 : aFreeMind Studio
*ID 230650 - 230699 : Unideal (https://www.uni-deal.com)
*ID 262700 - 262799: Scopen (https://www.scopen.fr)
*ID 274250 - 274299: Nerv Project (www.nerv-project.eu)
*ID 274300 - 274349: Knowhere Consulting S.L. (https://www.knowhere-consulting.eu)
*ID 274350: '''Free (take ranges of 50 only please, 1000 max per company)'''
*ID 320000 - 320999: Novus Studios (www.novusstudios.it)
*ID 321000 - 321999: AtooNet (http://www.atoo-net.com)
*ID 332000 - 332099: Gecka (https://gecka.nc)
*ID 332100 - 332149: Agence Milkshake (http://agencemilkshake.com)
*ID 332150 - 332199: Daniel Prowald IT – Service (https://prowald-it.de)
*ID 332200 - 332249: UNITICE (https://unitice.com)
*ID 332250 '''Free (take ranges of 50 only please, 1000 max per company)'''
*ID 330000 - 330049: XTEC Industries (www.xtec-ind.com)
*ID 330050 - 330099: 10100 S.R.L. - (www.10100.to)
*ID 330100 - 330149: AES Dana SRL (https://aes-dana.be)
*ID 330150 - 330199: Freshcore (https://www.freshcore.fr)
*ID 330200 - 399999: (take ranges of 50 only please, 1000 max per company)
*ID 400000 - 400999: 2byte.es (http://www.2byte.es)
*ID 401000 - 401999: B&D Informática
*ID 402000 - 402999: Marcos García de La Fuente (marcosgdf)
*ID 403000 - 403999: Sergibyte
*ID 404000 - 404999: Aikhan
*ID 405000 - 405999: AIME (http://www.aime.mx)
*ID 409000 - 409999: LliureTIC (www.lliuretic.cat)
*ID 420000 - 420099: BBS Concept
*ID 420100 - 420199: LeMousticProduction (www.lemousticproduction.info) -< module DoliRH
*ID 420200 - 421199: VatCheck (www.abnc.be)
*ID 422200 - 422999: Artaban (http://artaban.fr)
*ID 423000 - 423050: cyberesprit
*ID 423051 - 423099: R.Bossard
*ID 423100 - 423199: Joliciel (www.joliciel.fr)
*ID 424000 - 424049: A3sys - Mon-Dolibarr (http://www.mon-dolibarr.fr) by Philazerty
*ID 424050 - 424099: Pragma-tech (www.pragma-tech.fr)
*ID 424100 - 424149: Ohoo Solutions (http://www.ohoosolutions.com)
*ID 424150 - 424199: DAGARCAM Informática (https://www.dagarcam.com/)
*ID 424200 '''Free (take ranges of 50 only please, 1000 max per company)'''
*ID 425000 - 425999: Sébastien SERRE Thivinfo (www.thivinfo.com)
*ID 426000 - 426099: Arkesis-Solution
*ID 426100 - 426149: GetLandy (www.getlandy.com)
*ID 426150 - 426649: OOB Software
*ID 426650 - 426849: Soft-Task Serviços e Sistemas (www.soft-task.com.br)
*ID 426850 - 427000: Bruno Caldas (https://github.com/BCaldas)
*ID 427001 - 427999: Kevin GUERRIER (alias xcl.saian)
*ID 428000 - 428099: af83
*ID 428100 - 428199: Arnaud Serrut - Adalon
*ID 428200 '''Free (take ranges of 50 only please, 1000 max per company)'''
*ID 429000 - 429999: induslab
*ID 430000 - 430099: Mixity sprl (www.mixity.be)
*ID 430100 - 430199: sgiraud
*ID 430200 - 430299: Merlion TI (www.merlion-si.com.br)
*ID 430300 - 431299: Libre Expert (www.libre-expert.com)
*ID 431300 - 431399: ptibogxiv (www.ptibogxiv.net)
*ID 431400 - 431499: Befox (www.befox.fr)
*ID 431500 - 431599: rue Béjo (www.ruebejo.fr)
*ID 431600 - 431699: Avizzeo (www.avizzeo.com)
*ID 431700 - 432199: Multisistemas (www.multisistemas.com.sv)
*ID 432200 - 432399: Burbuja - Chile (www.burbuja.cl)
*ID 432400 - 433399: INOVEA CONSEIL (https://www.inovea-conseil.com)
*ID 433400 - 434399: Rachid HRICH - Maroc (HricH ServiceS.)
*ID 434400 - 435399: Lance Bleakley - LanceIT (www.lanceit.net)
*ID 436000 - 436099: SOWEBIO (www.soweb.io)
*ID 436100 - 436199: CAP-REL (www.cap-rel.fr)
*ID 436200 '''Free (take ranges of 50 only please at once, 1000 max per company)'''
*ID 436400 - 437399: Mohamed AHERDANE - Morocco - IT Consultant ( www.wave.ma )
*ID 437400 '''Free (take ranges of 50 only please at once, 1000 max per company)'''
*ID 438400 - 439399: Tetras Libre - France - Développement logiciels libres (www.tetras-libre.fr)
*ID 439400 - 440399: Dolibarr-pro - France - Développement Dolibarr (www.dolibarr-pro.com)
*ID 440400 - 441399: Quidlab Co., Ltd - Thailand - ( www.quidlab.com )
*ID 441400 - 442399: Ide@log - France - (https://www.idealog-info.net) - Laurent Leblanc
*ID 442400 - 443399: Valerio Bianchi (www.valeriobianchi.com)
*ID 443400 - 444399: delassalle - France - (www.delassalle.fr) - Joseph Delassalle
*ID 444400 - 445399: Webartis - Maroc - (www.webartis.net) - François Dry
*ID 445400 - 445499: SCOP Au-delà des nuages - France
*ID 446000 - 446999: iouston (http://www.iouston.com) - France - Julien Marchand
*ID 447000 - 447999: rSanjoSEO - Rafael San José Tovar (www.rsanjoseo.com) - Spain
*ID 448000 - 448999: Code 42 (www.code42.fr)
*ID 449000 - 449999: TakePOS (www.takepos.com)
*ID 450000 - 450999: Pierre ARDOIN
*ID 451000 - 451999: Éditeur depordi.fr
*ID 452000 - 452999: Dylan NAKONG
*ID 453000 - 453999: Menahd Ouchenir - France - menahd-ouchenir.com
*ID 454000 - 454999: Withheld - Canada
*ID 455000 - 455999: Gaëtan MAISON - Info Libre @ Dom - France (https://www.infolibreadom.com)
*ID 456000 - 456999: Laurent LEBLEU - B.L.C. - Blue Line Company - Lille - France (www.bluelinecompany.fr/dolibarr)
*ID 457000 - 457999: Sébastien BOUCHER
*ID 458000 - 458999: Lester HERNÁNDEZ - Argentina - (freelancerlrhd@gmail.com)
*ID 459000 - 459999: Infopen - France
*ID 460000 - 460050: torvista - Spain
*ID 461000 - 461999: MEGALOGI - Maroc (www.erpcloud.ma)
*ID 462000 - 462999: Making Digital (www.making-digital.fr) - France
*ID 463000 - 463999: linx s.r.l.s.
*ID 464000 - 464999: NimbleCubed Inc. (www.nimblecubed.com)
*ID 465000 - 465999: Artefacts - CourantAlternatif
*ID 466000 - 466999: CDM Consultores - (www.cdm.guru)
*ID 467000 - 467999: M71 Service GmbH - (www.m71-service.de)
*ID 468000 - 468049: Clément Segonzac - France (clement.segonzac@gmail.com)
*ID 468050 - 468099: Flavien Belli - France (https://github.com/Marshlyin || belliflaviencontactpro@gmail.com)
*ID 468100 - 468119: Chl (https://code.bugness.org/Dolibarr)
*ID 468120 - 468170: Commotron GmbH (https://www.commotron.com/)
*ID 468171 - 468174 '''Free (take ranges of 50 only please at once, 1000 max per company)'''
*ID 468175 - 468199: Gaëlle Rauffet - France (kiwiscan.net)
*ID 468200 - 468250: Paulo Oliveira - Brasil (paulorcdo@gmail.com)
*ID 468251 - 468270: CD-Systems - France (https://www.cd-systems.fr)
*ID 468300 - 468349: Uvensys - Germany (https://uvensys.de)
*ID 468350 - 468399 : Laudeco - Belgium (http://github.com/laudeco)
*ID 468400 - 468449 : Alexis LAURIER - France (https://www.alexislaurier.fr)
*ID 468450 - 468499 : Mehdi Belkhayat - Maroc (https://opensi.ma)
*ID 468500 - 468599 : InvIT GmbH - Germany (https://invit.sh)
*ID 468600 - 468649 : Ricardo Sequeira - Portugal (https://ricardo-sequeira.com)
*ID 468650 - 468699 : J-IT - Belgique (https://www.j-it.be)
*ID 468700 - 468749 : Fidesio - France (https://www.fidesio.com/)
*ID 468750 - 468799 : Sgestion - Spain (http://www.sgestion.net/)
*ID 468800 - 468849 : Denis JULIEN - Brasil (matrinxa@free.fr)
*ID 468850 - 468900: Mmariko - Module GED - Effios
*ID 468901 - 468950: Maazou Amadou Abdoul aziz - Maroc (yaronfada@gmail.com)
*ID 468951 - 469000: Alexis LAURIER - France (https://www.alexislaurier.fr)

...

=ID > 500000=

This range can't be reserved. It is a common range. If you don't plan to distribute your module, you can use an ID in this range with no need to reserve it.

{{Flag en}}
If you don't already have reserved ids and need some, please don't use hazardous number and use a number higher than 500000, but it is better to ask a wiki account, and reserve your own range by editing the 100000 - 499999 range (50 ids at once, 1000 ids maximum per partner).

{{Flag fr}}
Si vous n'avez pas de numéros réservés et en avez besoin, n'utilisez pas de chiffres au hasard et utilisez une valeur supérieure à 500000, toutefois, il est préférable d'obtenir un compte wiki, et réserver vous-même votre plage en ajoutant votre entrée dans la zone 100000 - 499999 (par lot de 50 d'abord, pas plus de 1000 numéros par partenaire).

{{Flag sp}}
Si no dispone de número reservado y necesita, no use cifras redondeadas y usa un valor superior a 500000. Si tiene una cuenta wiki, puede reservarse usted mismo sus id añadiendo su entrada en la zona 100000 - 499999 (no más de 1000 id por partner).