From a0f515ef124f634ab88157cebf30ceea097d52ee Mon Sep 17 00:00:00 2001 From: MDW Date: Wed, 13 Nov 2024 23:58:32 +0100 Subject: [PATCH] Qual: Improve write_file typing (part 2) (#30527) * Qual: Add abstract write_file to ModeleDon And update phpdoc for derived classes * Qual: Add abstract write_file to ModeleChequeReceipts And update phpdoc for derived classes * Qual: Add abstract write_file to ModelePDFRecruitmentCandidature And update phpdoc for derived classes * Qual: Add abstract write_file to ModelePDFStock & ModelePDFStockTransfer And update phpdoc for derived classes * Qual: Update phpdoc write_file for CommonStickerGenerator classes --------- Co-authored-by: Laurent Destailleur --- .../class/commonstickergenerator.class.php | 9 +++++---- .../modules/cheque/doc/pdf_blochet.class.php | 2 +- .../modules/cheque/modules_chequereceipts.php | 5 ++++- .../core/modules/dons/html_cerfafr.modules.php | 6 +++--- .../core/modules/dons/html_generic.modules.php | 6 +++--- htdocs/core/modules/dons/modules_don.php | 11 +++++++++++ .../member/doc/pdf_standard_member.class.php | 18 +++++++++--------- .../printsheet/doc/pdf_standardlabel.class.php | 4 ++-- .../printsheet/doc/pdf_tcpdflabel.class.php | 4 ++-- .../stocktransfer/doc/pdf_eagle.modules.php | 5 +++-- htdocs/don/class/don.class.php | 12 +++++++----- .../recruitment/admin/setup_candidatures.php | 2 ++ .../modules_recruitmentcandidature.php | 16 ++++++++++++++++ 13 files changed, 68 insertions(+), 32 deletions(-) diff --git a/htdocs/core/class/commonstickergenerator.class.php b/htdocs/core/class/commonstickergenerator.class.php index 8dc612176d8..564684d2ccc 100644 --- a/htdocs/core/class/commonstickergenerator.class.php +++ b/htdocs/core/class/commonstickergenerator.class.php @@ -131,13 +131,14 @@ abstract class CommonStickerGenerator extends CommonDocGenerator /** * Function to build PDF on disk, then output on HTTP stream. * - * @param array $arrayofrecords Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>) + * @param Adherent|array $arrayofrecords Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>) * @param Translate $outputlangs Lang object for output language * @param string $srctemplatepath Full path of source filename for generator using a template file - * @param string $outputdir Output directory for pdf file - * @return int 1=OK, 0=KO + * @param string $outputdir Output directory for pdf file + * @param string $filename Short file name of output file + * @return int<-1,1> 1=OK, <=0=KO */ - abstract public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = ''); + abstract public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = '', $filename = ''); // phpcs:enable /** diff --git a/htdocs/core/modules/cheque/doc/pdf_blochet.class.php b/htdocs/core/modules/cheque/doc/pdf_blochet.class.php index a2ce99ae903..a5c00ad81bd 100644 --- a/htdocs/core/modules/cheque/doc/pdf_blochet.class.php +++ b/htdocs/core/modules/cheque/doc/pdf_blochet.class.php @@ -116,7 +116,7 @@ class BordereauChequeBlochet extends ModeleChequeReceipts * @param string $_dir Directory * @param string $number Number * @param Translate $outputlangs Lang output object - * @return int 1=ok, 0=ko + * @return int<-1,1> 1 if OK, <=0 if KO */ public function write_file($object, $_dir, $number, $outputlangs) { diff --git a/htdocs/core/modules/cheque/modules_chequereceipts.php b/htdocs/core/modules/cheque/modules_chequereceipts.php index bf701ac64d4..c38fe64d5fc 100644 --- a/htdocs/core/modules/cheque/modules_chequereceipts.php +++ b/htdocs/core/modules/cheque/modules_chequereceipts.php @@ -111,6 +111,8 @@ abstract class ModeleChequeReceipts extends CommonDocGenerator return $list; } + + // phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps /** * Fonction to generate document on disk @@ -167,7 +169,8 @@ function chequereceipt_pdf_create($db, $id, $message, $modele, $outputlangs) // We save charset_output to restore it because write_file can change it if needed for // output format that does not support UTF8. $sav_charset_output = $outputlangs->charset_output; - if ($obj->write_file($id, $outputlangs) > 0) { + // TODO: write_file seems invalid, function is likely no longer used - delete ? + if ($obj->write_file($id, $outputlangs) > 0) { // @phan-suppress-current-line PhanParamTooFew,PhanPluginSuspiciousParamPosition $outputlangs->charset_output = $sav_charset_output; return 1; } else { diff --git a/htdocs/core/modules/dons/html_cerfafr.modules.php b/htdocs/core/modules/dons/html_cerfafr.modules.php index bf2364426e8..7e76bf0a10f 100644 --- a/htdocs/core/modules/dons/html_cerfafr.modules.php +++ b/htdocs/core/modules/dons/html_cerfafr.modules.php @@ -69,10 +69,10 @@ class html_cerfafr extends ModeleDon /** * Write the object to document file to disk * - * @param Don $don Donation object - * @param Translate $outputlangs Lang object for output language + * @param Don $don Donation object + * @param Translate $outputlangs Lang object for output language * @param string $currency Currency code - * @return int >0 if OK, <0 if KO + * @return int<-1,1> >0 if OK, <0 if KO */ public function write_file($don, $outputlangs, $currency = '') { diff --git a/htdocs/core/modules/dons/html_generic.modules.php b/htdocs/core/modules/dons/html_generic.modules.php index 2f3b8ae30cd..622c8139cc0 100644 --- a/htdocs/core/modules/dons/html_generic.modules.php +++ b/htdocs/core/modules/dons/html_generic.modules.php @@ -186,10 +186,10 @@ class html_generic extends ModeleDon /** * Write the object to document file to disk * - * @param Don $don Donation object - * @param Translate $outputlangs Lang object for output language + * @param Don $don Donation object + * @param Translate $outputlangs Lang object for output language * @param string $currency Currency code - * @return int >0 if OK, <0 if KO + * @return int<-1,1> >0 if OK, <0 if KO */ public function write_file($don, $outputlangs, $currency = '') { diff --git a/htdocs/core/modules/dons/modules_don.php b/htdocs/core/modules/dons/modules_don.php index 6aa58b432d0..81fa40f93fb 100644 --- a/htdocs/core/modules/dons/modules_don.php +++ b/htdocs/core/modules/dons/modules_don.php @@ -55,6 +55,17 @@ abstract class ModeleDon extends CommonDocGenerator return $list; } + + // phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps + /** + * Write the object to document file to disk + * + * @param Don $don Donation object + * @param Translate $outputlangs Lang object for output language + * @param string $currency Currency code + * @return int<-1,1> >0 if OK, <0 if KO + */ + abstract public function write_file($don, $outputlangs, $currency = ''); } diff --git a/htdocs/core/modules/member/doc/pdf_standard_member.class.php b/htdocs/core/modules/member/doc/pdf_standard_member.class.php index 74373fa4e99..3adbb53d53f 100644 --- a/htdocs/core/modules/member/doc/pdf_standard_member.class.php +++ b/htdocs/core/modules/member/doc/pdf_standard_member.class.php @@ -262,17 +262,17 @@ class pdf_standard_member extends CommonStickerGenerator // phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps /** - * Function to build PDF on disk, then output on HTTP stream. + * Function to build PDF on disk, then output on HTTP stream. * - * @param Adherent|array $object Member object. Old usage: Array of record information (array('textleft'=>,'textheader'=>, ...'id'=>,'photo'=>) - * @param Translate $outputlangs Lang object for output language - * @param string $srctemplatepath Full path of source filename for generator using a template file. Example: '5161', 'AVERYC32010', 'CARD', ... - * @param string $mode Tell if doc module is called for 'member', ... - * @param int $nooutput 1=Generate only file on disk and do not return it on response - * @param string $filename Name of output file (without extension) - * @return int 1=OK, 0=KO + * @param Adherent|array $object Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>) + * @param Translate $outputlangs Lang object for output language + * @param string $srctemplatepath file. Example: '5161', 'AVERYC32010', 'CARD', ... + * @param string $mode Tell if doc module is called + * @param string $nooutput 1=Generate only file on disk and do not return it on response // TODO: Fix not compatible parameter signature. + * @param string $filename Name of output file (without extension) + * @return int<-1,1> 1=OK, <=0=KO */ - public function write_file($object, $outputlangs, $srctemplatepath, $mode = 'member', $nooutput = 0, $filename = 'tmp_cards') + public function write_file($object, $outputlangs, $srctemplatepath, $mode = 'member', $nooutput = '', $filename = 'tmp_cards') { // phpcs:enable global $user, $conf, $langs, $mysoc, $_Avery_Labels; diff --git a/htdocs/core/modules/printsheet/doc/pdf_standardlabel.class.php b/htdocs/core/modules/printsheet/doc/pdf_standardlabel.class.php index d8713404fdc..6e81bbe71df 100644 --- a/htdocs/core/modules/printsheet/doc/pdf_standardlabel.class.php +++ b/htdocs/core/modules/printsheet/doc/pdf_standardlabel.class.php @@ -228,12 +228,12 @@ class pdf_standardlabel extends CommonStickerGenerator /** * Function to build PDF on disk, then output on HTTP stream. * - * @param array $arrayofrecords Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>) + * @param array $arrayofrecords Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>) * @param Translate $outputlangs Lang object for output language * @param string $srctemplatepath Full path of source filename for generator using a template file * @param string $outputdir Output directory for pdf file * @param string $filename Short file name of PDF output file - * @return int 1=OK, 0=KO + * @return int<-1,1> 1=OK, <=0=KO */ public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = '', $filename = 'tmp_address_sheet.pdf') { diff --git a/htdocs/core/modules/printsheet/doc/pdf_tcpdflabel.class.php b/htdocs/core/modules/printsheet/doc/pdf_tcpdflabel.class.php index 99b12c9180b..ca15b14e565 100644 --- a/htdocs/core/modules/printsheet/doc/pdf_tcpdflabel.class.php +++ b/htdocs/core/modules/printsheet/doc/pdf_tcpdflabel.class.php @@ -250,14 +250,14 @@ class pdf_tcpdflabel extends CommonStickerGenerator // phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps /** - * Function to build PDF on disk, then output on HTTP stream. + * Function to build PDF on disk, then output on HTTP stream. * * @param Adherent|array|bool}> $arrayofrecords Array of record information (array('textleft'=>,'textheader'=>, ..., 'id'=>,'photo'=>) * @param Translate $outputlangs Lang object for output language * @param string $srctemplatepath Full path of source filename for generator using a template file * @param string $outputdir Output directory for pdf file * @param string $filename Short file name of PDF output file - * @return int 1=OK, 0=KO + * @return int<-1,1> 1=OK, <=0=KO */ public function write_file($arrayofrecords, $outputlangs, $srctemplatepath, $outputdir = '', $filename = 'tmp_address_sheet.pdf') { diff --git a/htdocs/core/modules/stocktransfer/doc/pdf_eagle.modules.php b/htdocs/core/modules/stocktransfer/doc/pdf_eagle.modules.php index 0d46ae1b102..56910f912b4 100644 --- a/htdocs/core/modules/stocktransfer/doc/pdf_eagle.modules.php +++ b/htdocs/core/modules/stocktransfer/doc/pdf_eagle.modules.php @@ -169,17 +169,18 @@ class pdf_eagle extends ModelePDFStockTransfer } } + // phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps /** * Function to build pdf onto disk * * @param StockTransfer $object Object StockTransfer to generate (or id if old method) - * @param Translate $outputlangs Lang output object + * @param Translate $outputlangs Lang output object * @param string $srctemplatepath Full path of source filename for generator using a template file * @param int<0,1> $hidedetails Do not show line details * @param int<0,1> $hidedesc Do not show desc * @param int<0,1> $hideref Do not show ref - * @return int<-1,1> 1=OK, 0=KO + * @return int<-1,1> 1 if OK, <=0 if KO */ public function write_file($object, $outputlangs, $srctemplatepath = '', $hidedetails = 0, $hidedesc = 0, $hideref = 0) { diff --git a/htdocs/don/class/don.class.php b/htdocs/don/class/don.class.php index eac251a8cf0..9ba0ac8de98 100644 --- a/htdocs/don/class/don.class.php +++ b/htdocs/don/class/don.class.php @@ -1019,14 +1019,14 @@ class Don extends CommonObject /** - * Create a document onto disk according to template module. + * Create a document on disk according to template module. * * @param string $modele Force template to use ('' to not force) * @param Translate $outputlangs object lang a utiliser pour traduction - * @param int $hidedetails Hide details of lines - * @param int $hidedesc Hide description - * @param int $hideref Hide ref - * @return int 0 if KO, 1 if OK + * @param int<0,1> $hidedetails Hide details of lines + * @param int<0,1> $hidedesc Hide description + * @param int<0,1> $hideref Hide ref + * @return int<-1,1> 0 if KO, 1 if OK */ public function generateDocument($modele, $outputlangs, $hidedetails = 0, $hidedesc = 0, $hideref = 0) { @@ -1098,6 +1098,8 @@ class Don extends CommonObject $classname = $modele; $obj = new $classname($this->db); + '@phan-var-force ModeleDon $obj'; + // We save charset_output to restore it because write_file can change it if needed for // output format that does not support UTF8. $sav_charset_output = $outputlangs->charset_output; diff --git a/htdocs/recruitment/admin/setup_candidatures.php b/htdocs/recruitment/admin/setup_candidatures.php index 2eff5a82d6e..2695b32e7b6 100644 --- a/htdocs/recruitment/admin/setup_candidatures.php +++ b/htdocs/recruitment/admin/setup_candidatures.php @@ -118,6 +118,8 @@ if ($action == 'updateMask') { $module = new $classname($db); + '@phan-var-force ModelePDFRecruitmentCandidature $module'; + if ($module->write_file($tmpobject, $langs) > 0) { header("Location: ".DOL_URL_ROOT."/document.php?modulepart=".strtolower($tmpobjectkey)."&file=SPECIMEN.pdf"); return; diff --git a/htdocs/recruitment/core/modules/recruitment/modules_recruitmentcandidature.php b/htdocs/recruitment/core/modules/recruitment/modules_recruitmentcandidature.php index 7d7bfadd13d..ca356cae81c 100644 --- a/htdocs/recruitment/core/modules/recruitment/modules_recruitmentcandidature.php +++ b/htdocs/recruitment/core/modules/recruitment/modules_recruitmentcandidature.php @@ -58,6 +58,22 @@ abstract class ModelePDFRecruitmentCandidature extends CommonDocGenerator return $list; } + + + // phpcs:disable PEAR.NamingConventions.ValidFunctionName.ScopeNotCamelCaps + /** + * Function to build a document on disk using the generic odt module. + * + * @param RecruitmentCandidature $object Object source to build document + * @param Translate $outputlangs Lang output object + * @param string $srctemplatepath Full path of source filename for generator using a template file + * @param int<0,1> $hidedetails Do not show line details + * @param int<0,1> $hidedesc Do not show desc + * @param int<0,1> $hideref Do not show ref + * @return int<-1,1> 1 if OK, <=0 if KO + */ + abstract public function write_file($object, $outputlangs, $srctemplatepath = '', $hidedetails = 0, $hidedesc = 0, $hideref = 0); + // phpcs:enable }